---
title: "Usage history, bucketed by day or endpoint — read-only, never bills"
method: GET
path: "/v1/usage"
---

# Usage history, bucketed by day or endpoint — read-only, never bills

`GET /v1/usage`

## Request

- Base URL: `https://framefetch.net`
- URL: `https://framefetch.net/v1/usage`
- Auth: HTTP bearer

Read-only usage history for the calling account over a date range, bucketed by calendar day (group=day, default) or by endpoint (group=endpoint). Defaults to the trailing 30 days when from/to are omitted; the range is capped at 366 days.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `group` 'day' | 'endpoint'

## Response `200`

Bucketed usage

- UsageResult
  - `items` object[]
    - `bucket` string: 'YYYY-MM-DD' for group=day; the endpoint string (or 'unattributed') for group=endpoint.
    - `calls` integer
    - `cost_micros` integer
  - `total_micros` integer

## Other responses

- `400`: Error envelope
- `401`: Error envelope
- `429`: Error envelope

---

[API](https://skmtc.dev/framefetch/apis/framefetch-api.md) · [All operations](https://skmtc.dev/framefetch/apis/framefetch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/framefetch/apis/framefetch-api/revisions/5584e8eb9bf5?raw)