---
title: "Get asset counts"
method: GET
path: "/api/assets/counts"
tags: ["assets"]
---

# Get asset counts

`GET /api/assets/counts`

Counts assets bucketed by time period — use this to summarize a library (or a filtered slice) without paging through the full timeline. Returns one row per bucket, ordered most-recent-first, with optional filtering by album, person, date range, or trash state.

To list the actual assets within a bucket, call `list_assets` with the same filters and a `local_datetime_after` / `local_datetime_before` window matching the bucket. Does not filter by image content or location; for content-based search use `search_assets`.

**Pagination:** When `has_more` is true, pass the last `time_bucket` value from `data` as `local_datetime_before` to fetch the next page.

## Query parameters

- `library_id` string, nullable — Library to count assets in. Optional if the user has a single live (non-trashed) library; required when they have multiple.
- `group_by` 'month' — Time period to group counts by. Only `month` is supported; other values return 422.
- `album_id` string, nullable — Return only assets in this album — the album's `album_` ID, not its name.
- `person_id` string, nullable — Count only assets containing a face belonging to this person.
- `local_datetime_after` string, date-time, nullable — Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. `local_datetime` is the photo's wall-clock time in the device's own timezone. Naive values compare directly against `local_datetime`. Timezone-aware values: assets with a known offset are compared in UTC (`local_datetime - offset`); assets without an offset fall back to wall-clock comparison against `local_datetime`.
- `local_datetime_before` string, date-time, nullable — Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as `local_datetime_after`.
- `state` 'live' | 'trashed' | 'all' — Which set of assets to count: `live` (default — excludes trashed assets), `trashed` (only trashed assets), or `all` (both live and trashed).
- `limit` integer — Maximum number of time buckets to return per page (1–200). Defaults to 20.

## Response `200`

Successful Response

- AssetCountsResponse
  - `data` TimeBucketCount[], required — Time bucket and count pairs, ordered by time bucket descending
    - `time_bucket` string, date-time, required — Start of the time period
    - `count` integer, required — Number of assets in this time period
  - `has_more` boolean, required — True if there are more time buckets. To fetch the next page, pass the last `time_bucket` value as `local_datetime_before` (exclusive — buckets starting before that value are returned).

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Not found
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/versions/e71db45f5d4a/schema)