---
title: "Get token usage metrics"
method: POST
path: "/llm/tokens"
tags: ["Llm"]
---

# Get token usage metrics

`POST /llm/tokens`

## Request

- Base URL: `https://api.your-domain.com`
- URL: `https://api.your-domain.com/llm/tokens`
- Auth: API key in header `X-API-KEY`
- TypeScript: <https://skmtc.dev/neulandai/apis/neuland-ai-hub-api/docs/llm/tokens/post.ts> (a function with typed inputs; its response is checked against the schema)

Return current-month token totals and per-model token timeseries for the tenant.

## Query parameters

- `cookie_name` string, nullable
- `tenant_id` integer

## Request body

- UsageRequest: Generic usage request model for both token and cost queries.
  - `granularity` 'monthly' | 'yearly' | 'custom', required: Aggregation window; 'custom' requires date_start and date_end.
  - `date_start` string, date-time, nullable: Start of the custom range (used only when granularity is 'custom').
  - `date_end` string, date-time, nullable: End of the custom range (used only when granularity is 'custom').

## Response `200`

Successful Response

- TokensTimeseriesResponse: Response model for LLM tokens with timeseries data.
  - `total_prompt_tokens` number, required: Total prompt tokens across all models for the current month.
  - `total_completion_tokens` number, required: Total completion tokens across all models for the current month.
  - `total_requests` number, required: Total requests across all models for the current month.
  - `total_tokens` number, required: Total tokens (prompt + completion) for the current month.
  - `tokens_per_model` TokensPerModel[], required: Current-month token summary for each model.
    - `llm_model` string, required: Catalog name of the model.
    - `duration` string, required: Window the totals cover.
    - `total_tokens_count` number, required: Total tokens (prompt + completion) in the window.
    - `prompt_token_count` number, required: Prompt tokens consumed in the window.
    - `completion_token_count` number, required: Completion tokens generated in the window.
    - `total_requests` number, required: Number of requests in the window.
  - `timeseries_per_model` TokenTimeseriesPerModel[], required: Token usage timeseries for each model.
    - `llm_model` string, required: Catalog name of the model.
    - `timeseries` object, required: Per-metric timeseries keyed by metric name (PromptTokens, CompletionTokens, TotalTokens).

## Other responses

- `401`: Missing or invalid authentication.
- `403`: Admin privileges required.
- `422`: Validation Error

---

[API](https://skmtc.dev/neulandai/apis/neuland-ai-hub-api.md) - [All operations](https://skmtc.dev/neulandai/apis/neuland-ai-hub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/neulandai/apis/neuland-ai-hub-api/revisions/b53e89b98c2b?raw)