get_calendar_heatmap
See how many photos were taken or uploaded each day across a date range, revealing gaps, busy periods, and overall library health without listing assets.
Instructions
How many photos per day, over a date range — the data behind a calendar heatmap. Use this to find gaps (months with nothing), busy periods, or to check a library's health at a glance without listing assets. Immich 3.x answers natively; on Immich 2.x the same shape is built from the timeline (taken dates only), which costs one request per month in the range, so pass the narrowest range that answers the question. Read-only.
Args:
from_date: ISO date lower bound (e.g. '2026-01-01'). Omit for the server
default on Immich 3.x; on 2.x an omitted bound means the last 365 days,
because an open-ended range would walk every month of the library.
to_date: ISO date upper bound. Omit for the server default.
heatmap_type: 'Taken' (capture date, default) or 'Upload' (when it reached
Immich; 3.x only).
Returns: JSON with source ('immich' or 'timeline'), total and a series of
{date, count} for the days that have activity, oldest first (a day missing
from the series had nothing).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to_date | No | ||
| from_date | No | ||
| heatmap_type | No | Taken |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |