Usage API: Tracking Credit Consumption and Run Volume

The Usage API provides programmatic access to credit consumption and run volume across your Reindeer workspace. Use it to monitor spend, attribute usage to specific agents, and drill into the cost profile of individual runs.

Authentication and permissions

All requests use your workspace API base URL and a Bearer token:

https://<your-reindeer-domain>/api/v1

Both Usage API endpoints require a token with the Admin role. Requests with insufficient permissions return 403 FORBIDDEN.

Get workspace usage summary

GET /api/v1/workspaces/{workspace}/usage

Returns aggregated credit usage for the workspace, broken down by agent. Workspace and agent identifiers may be either the UUID or the resource name.

Filtering by date range

The endpoint supports filtering on created_at via the filter query parameter (AIP-160 syntax). Bounds are inclusive. When no filter is provided, all-time usage is returned.

GET /api/v1/workspaces/acme/usage?filter=created_at%20%3E=%20%222026-07-01T00:00:00Z%22%20AND%20created_at%20%3C%20%222026-08-01T00:00:00Z%22

Unencoded, the filter expression reads:

created_at >= "2026-07-01T00:00:00Z" AND created_at < "2026-08-01T00:00:00Z"

Response

{
  "total_credits": 12450,
  "total_runs": 318,
  "agents": [
    {
      "agent": "workspaces/acme/agents/invoice-validator",
      "credits": 9800,
      "run_count": 250
    },
    {
      "agent": "workspaces/acme/agents/document-classifier",
      "credits": 2650,
      "run_count": 68
    }
  ]
}

Get run usage detail

GET /api/v1/workspaces/{workspace}/agents/{agent}/runs/{run_id}/usage

Returns the credit breakdown for a single run. Each item represents credits consumed by one step of the run; items without a step field represent credits not attributed to any step (for example, run orchestration).

Response

{
  "total_credits": 42,
  "credit_items": [
    {
      "step": "workspaces/acme/agents/invoice-validator/runs/0198.../steps/0198...",
      "credits": 35
    },
    {
      "credits": 7
    }
  ]
}

Example: monthly usage report

curl -s -H "Authorization: Bearer $REINDEER_API_TOKEN" \
  "https://<your-reindeer-domain>/api/v1/workspaces/acme/usage" \
  --data-urlencode 'filter=created_at >= "2026-07-01T00:00:00Z" AND created_at < "2026-08-01T00:00:00Z"' -G

Error responses

Questions or feedback? Reach out to your Reindeer team — we are expanding the metrics surface and would love to hear which aggregations you need next.