---
title: "Get Usage"
method: GET
path: "/api/v1/cost/usage"
---

# Get Usage

`GET /api/v1/cost/usage`

## Request

- Base URL: `https://api.stacktrace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stacktrace.ai/api/v1/cost/usage`
- Auth: none declared

Tokens over the org's last days, by person, person and agent kind,
repo, model or agent.

## Query parameters

- `window` '1d' | '3d' | '7d' | '30d'
- `by` 'person' | 'person_kind' | 'repo' | 'model' | 'agent'

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- UsageViewResponse
  - `window` '1d' | '3d' | '7d' | '30d', required
  - `by` 'person' | 'person_kind' | 'repo' | 'model' | 'agent', required
  - `time_zone` string, required
  - `since` string, date-time, required
  - `until` string, date-time, required
  - `grain` 'hour' | 'day', required
  - `totals` UsageFigures, required: Tokens by kind, what they cost, and the two cache figures the console shows beside them (`stacktrace` cost-phase-2.md, "Usage views").
    - `cost` number
    - `input_cost` number
    - `output_cost` number
    - `cache_read_cost` number
    - `cache_write_cost` number
    - `unpriced` integer
    - `input` integer, required
    - `output` integer, required
    - `cache_read` integer, required
    - `cache_write` integer, required
    - `tokens` integer, required
    - `cache_read_share` number, nullable, required
    - `uncached_input` integer, required
  - `rows` UsageRow[], required
    - `cost` number
    - `input_cost` number
    - `output_cost` number
    - `cache_read_cost` number
    - `cache_write_cost` number
    - `unpriced` integer
    - `input` integer, required
    - `output` integer, required
    - `cache_read` integer, required
    - `cache_write` integer, required
    - `tokens` integer, required
    - `cache_read_share` number, nullable, required
    - `uncached_input` integer, required
    - `key` string, nullable, required
    - `agent_kind` string, nullable
    - `asset_display_name` string, nullable
    - `person_name` string, nullable
    - `runs` integer, required
    - `usual` integer, nullable, required
    - `usual_cost` number, nullable
  - `series` UsagePoint[], required
    - `cost` number
    - `input_cost` number
    - `output_cost` number
    - `cache_read_cost` number
    - `cache_write_cost` number
    - `unpriced` integer
    - `start` string, date-time, required
    - `tokens` integer, required
    - `input` integer
    - `output` integer
    - `cache_read` integer
    - `cache_write` integer
    - `models` UsageSlice[]
      - `key` string, nullable, required
      - `tokens` integer, required
      - `cost` number
      - `unpriced` integer
    - `agents` UsageSlice[]
      - `key` string, nullable, required
      - `tokens` integer, required
      - `cost` number
      - `unpriced` integer
    - `environments` UsageSlice[]
      - `key` string, nullable, required
      - `tokens` integer, required
      - `cost` number
      - `unpriced` integer
    - `person_agents` UsagePersonAgent[]
      - `person` string, nullable, required
      - `agent_kind` string, nullable, required
      - `tokens` integer, required
      - `cost` number
      - `unpriced` integer
      - `name` string, nullable
  - `agents` integer, required
  - `behind` integer, required
  - `truncated` boolean
  - `usual` integer, nullable
  - `usual_day` integer, nullable
  - `usual_cost` number, nullable
  - `usual_day_cost` number, nullable
  - `usual_by_now` integer, nullable
  - `usual_by_now_cost` number, nullable
  - `today_scored` integer, nullable
  - `today_scored_cost` number, nullable
  - `people` integer
  - `runs` integer
  - `agents_used` integer
  - `top_people` UsagePerson[]
    - `cost` number
    - `input_cost` number
    - `output_cost` number
    - `cache_read_cost` number
    - `cache_write_cost` number
    - `unpriced` integer
    - `key` string, nullable, required
    - `name` string, nullable, required
    - `tokens` integer, required
    - `input` integer
    - `output` integer
    - `cache_read` integer
    - `cache_write` integer
    - `models` UsageSlice[]
      - `key` string, nullable, required
      - `tokens` integer, required
      - `cost` number
      - `unpriced` integer
    - `agents` UsageSlice[]
      - `key` string, nullable, required
      - `tokens` integer, required
      - `cost` number
      - `unpriced` integer
  - `top_person_agents` UsagePersonAgent[]
    - `person` string, nullable, required
    - `agent_kind` string, nullable, required
    - `tokens` integer, required
    - `cost` number
    - `unpriced` integer
    - `name` string, nullable
  - `top_environments` UsageEnvironment[]
    - `agent_id` string, required
    - `agent_kind` string, nullable, required
    - `asset_display_name` string, nullable, required
    - `tokens` integer, required
    - `cost` number
    - `unpriced` integer
  - `top_runs` UsageTopRun[]
    - `agent_id` string, required
    - `run_id` string, required
    - `surface` 'chatgpt-work', nullable
    - `title` string, nullable, required
    - `repo` string, nullable, required
    - `branch` string, nullable, required
    - `agent_kind` string, nullable, required
    - `person` string, nullable, required
    - `person_name` string, nullable, required
    - `models` string[], required
    - `tokens` integer, required
    - `cost` number
    - `unpriced` integer
    - `share` number, required
    - `cache_read_share` number, nullable, required
    - `first_hour` string, date-time, required
    - `last_hour` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/stacktrace/apis/stacktrace-fleet-api.md) - [All operations](https://skmtc.dev/stacktrace/apis/stacktrace-fleet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stacktrace/apis/stacktrace-fleet-api/revisions/0ee5484d1d0b?raw)