> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get asset 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.



## OpenAPI

````yaml https://api.gumnut.ai/openapi.json get /api/assets/counts
openapi: 3.1.0
info:
  title: Gumnut API
  description: API for using Gumnut to manage photos and videos
  version: 0.1.0
servers: []
security: []
paths:
  /api/assets/counts:
    get:
      tags:
        - assets
      summary: Get asset counts
      description: >-
        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.
      operationId: get_asset_counts
      parameters:
        - name: library_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Library to count assets in (optional)
            title: Library Id
          description: Library to count assets in (optional)
        - name: group_by
          in: query
          required: false
          schema:
            const: month
            type: string
            description: >-
              Time period to group counts by. Only `month` is supported; other
              values return 422.
            default: month
            title: Group By
          description: >-
            Time period to group counts by. Only `month` is supported; other
            values return 422.
        - name: album_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Album Id
            description: >-
              Return only assets in this album — the album's `album_` ID, not
              its name.
          description: >-
            Return only assets in this album — the album's `album_` ID, not its
            name.
        - name: person_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by assets associated with a specific person ID
            title: Person Id
          description: Filter by assets associated with a specific person ID
        - name: local_datetime_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Local Datetime After
            description: >-
              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`.
          description: >-
            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`.
        - name: local_datetime_before
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: Local Datetime Before
            description: >-
              Only include assets captured strictly before this instant (ISO
              8601; exclusive). Same conversion requirement and awareness/offset
              semantics as `local_datetime_after`.
          description: >-
            Only include assets captured strictly before this instant (ISO 8601;
            exclusive). Same conversion requirement and awareness/offset
            semantics as `local_datetime_after`.
        - name: state
          in: query
          required: false
          schema:
            enum:
              - live
              - trashed
              - all
            type: string
            description: >-
              Which set of assets to count: `live` (default — excludes trashed
              assets), `trashed` (only trashed assets), or `all` (both live and
              trashed).
            default: live
            title: State
          description: >-
            Which set of assets to count: `live` (default — excludes trashed
            assets), `trashed` (only trashed assets), or `all` (both live and
            trashed).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: Maximum number of time buckets to return (1-200)
            default: 20
            title: Limit
          description: Maximum number of time buckets to return (1-200)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetCountsResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AssetCountsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/TimeBucketCount'
          type: array
          title: Data
          description: Time bucket and count pairs, ordered by time bucket descending
        has_more:
          type: boolean
          title: Has More
          description: >-
            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).
      type: object
      required:
        - data
        - has_more
      title: AssetCountsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TimeBucketCount:
      properties:
        time_bucket:
          type: string
          format: date-time
          title: Time Bucket
          description: Start of the time period
        count:
          type: integer
          title: Count
          description: Number of assets in this time period
      type: object
      required:
        - time_bucket
        - count
      title: TimeBucketCount
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````