---
title: "Get all document token usage"
method: GET
path: "/api/v0/knowledge-bases/stats/token-usage"
tags: ["Knowledge Bases"]
---

# Get all document token usage

`GET /api/v0/knowledge-bases/stats/token-usage`

Get token usage / cost tracking across all of the user's documents.

## Response `200`

Successful Response

- TokenUsageResponse — Response for token usage / cost tracking over a set of documents (a knowledge base, the whole account, or an explicit document list).
  - `total_input_tokens` integer, required — Total input tokens across all documents.
  - `total_output_tokens` integer, required — Total output tokens across all documents.
  - `total_estimated_cost_usd` number, required — Total estimated cost in USD (calculated live from current pricing).
  - `total_duration_ms` integer, required — Total LLM call duration in milliseconds across all documents.
  - `total_llm_calls` integer, required — Total number of LLM calls.
  - `model_usage` ModelTokenUsageItem[], required — Token usage breakdown 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.
    - `output_tokens` integer, required — Total output tokens for this model.
    - `estimated_cost_usd` number, required — Estimated cost in USD (calculated live from current pricing).
    - `num_calls` integer, required — Number of LLM calls.
    - `duration_ms` integer, required — Total LLM call duration in milliseconds.
  - `step_usage` StepTokenUsageItem[], required — Token usage breakdown 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.
    - `output_tokens` integer, required — Total output tokens for this task type and step.
    - `estimated_cost_usd` number, required — Estimated cost in USD (calculated live from current pricing).
    - `num_calls` integer, required — Number of LLM calls.
    - `duration_ms` integer, required — Total LLM call duration in milliseconds.
  - `document_usage` DocumentTokenUsageItem[], required — Token usage breakdown by document.
    - `document_id` string, uuid, required — The document public UUID.
    - `name` string, required — The document name.
    - `input_tokens` integer, required — Total input tokens.
    - `output_tokens` integer, required — Total output tokens.
    - `estimated_cost_usd` number, required — Estimated cost in USD (calculated live from current pricing).
    - `num_calls` integer, required — Number of LLM calls.
    - `duration_ms` integer, required — Total LLM call duration in milliseconds.

---

[API](https://skmtc.dev/outerport/apis/outerport-api.md) · [All operations](https://skmtc.dev/outerport/apis/outerport-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/outerport/outerport-api/revisions/f565b46daaea/schema)