---
title: "Get LLM usage and estimated cost"
method: GET
path: "/api/v0/usage"
tags: ["Usage"]
---

# Get LLM usage and estimated cost

`GET /api/v0/usage`

## Request

- Base URL: `https://api.outerport.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.outerport.com/api/v0/usage`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/outerport/apis/outerport-api/docs/api/v0/usage/get.ts> (a function with typed inputs; its response is checked against the schema)

Aggregate LLM token usage and estimated cost over a range of UTC days, broken down by model, by task step, and by what the spend was for.

## Query parameters

- `start` string, date, nullable: Only count usage on or after this UTC day.
- `end` string, date, nullable: Only count usage strictly before this UTC day.
- `owner_kind` 'document' | 'agent_run' | 'question' | 'knowledge_base' | 'knowledge_graph' | 'schematic' | 'experiment' | 'unattributed': What a block of LLM spend is attributable to.

## Response `200`

Successful Response

- UsageResponse: LLM usage and estimated cost across every kind of owner.
  - `total_input_tokens` integer, required: Total input tokens.
  - `total_cached_input_tokens` integer: Total tokens served from the prompt cache.
  - `total_output_tokens` integer, required: Total output tokens.
  - `total_estimated_cost_usd` number, required: Total estimated cost in USD, at the price in force on the day of each call.
  - `total_duration_ms` integer, required: Total LLM call duration in ms.
  - `total_llm_calls` integer, required: Total number of LLM calls.
  - `model_usage` ModelTokenUsageItem[], required: Usage broken down by model.
    - `model` string, required: The model name.
    - `provider` string, required: The provider (e.g., openai, gemini).
    - `input_tokens` integer, required: Total input tokens for this model.
    - `cached_input_tokens` integer: Subset of input_tokens served from the provider's prompt cache, billed at the cache-read rate rather than the full input rate.
    - `output_tokens` integer, required: Total output tokens for this model.
    - `estimated_cost_usd` number, required: Estimated cost in USD, at the price in force on the day of each call.
    - `num_calls` integer, required: Number of LLM calls.
    - `duration_ms` integer, required: Total LLM call duration in milliseconds.
  - `step_usage` StepTokenUsageItem[], required: Usage broken down by task type and step.
    - `task_type` string, required: The task type (e.g., vlm, search, reasoning).
    - `step` string, required: The step within the task type (e.g., vlm_generation, text_refinement). Task types can span more than one model role; the step separates them.
    - `input_tokens` integer, required: Total input tokens for this task type and step.
    - `cached_input_tokens` integer: Subset of input_tokens served from the provider's prompt cache, billed at the cache-read rate rather than the full input rate.
    - `output_tokens` integer, required: Total output tokens for this task type and step.
    - `estimated_cost_usd` number, required: Estimated cost in USD, at the price in force on the day of each call.
    - `num_calls` integer, required: Number of LLM calls.
    - `duration_ms` integer, required: Total LLM call duration in milliseconds.
  - `owner_usage` OwnerUsageItem[], required: Usage broken down by what it was spent on.
    - `owner_kind` string, required: What the spend is attributable to: document, agent_run, question, knowledge_base, knowledge_graph, schematic, experiment, or unattributed (a call made outside any instrumented entry point).
    - `input_tokens` integer, required: Total input tokens.
    - `cached_input_tokens` integer: Subset of input_tokens served from the prompt cache.
    - `output_tokens` integer, required: Total output tokens.
    - `estimated_cost_usd` number, required: Estimated cost in USD, at the price in force on the day of each call.
    - `num_calls` integer, required: Number of LLM calls.
    - `duration_ms` integer, required: Total LLM call duration in milliseconds.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-13** `7f81908bcdfe`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/outerport/apis/outerport-api/changes/api/v0/usage/get.md)

---

[API](https://skmtc.dev/outerport/apis/outerport-api.md) - [All operations](https://skmtc.dev/outerport/apis/outerport-api/llms.txt) - [OpenAPI document](https://skmtc.dev/outerport/apis/outerport-api/revisions/08b5bf6f7f18?raw)