---
title: "Get external service usage costs"
method: POST
path: "/llm/services/cost"
tags: ["Llm"]
---

# Get external service usage costs

`POST /llm/services/cost`

## Request

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

Return non-LLM service usage costs aggregated by source, model, and time period.

## Query parameters

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

## Request body

- UsageCostRequest
  - `granularity` 'monthly' | 'yearly' | 'custom': 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').
  - `source` string, nullable: Filter by usage source (e.g. doc_intelligence, interpreter).
  - `model` string, nullable: Filter by specific model catalog name.
  - `provider` string, nullable: Filter by provider.

## Response `200`

Successful Response

- UsageCostResponse
  - `start_date` string, date-time, required: Start of the aggregation window.
  - `end_date` string, date-time, required: End of the aggregation window.
  - `total_cost` number, required: Total cost across the window.
  - `total_tokens` integer, required: Total tokens across the window.
  - `total_prompt_tokens` integer, required: Total prompt tokens across the window.
  - `total_completion_tokens` integer, required: Total completion tokens across the window.
  - `total_cached_tokens` integer, required: Total cached prompt tokens across the window.
  - `record_count` integer, required: Total number of usage records.
  - `by_source` CostBySource[], required: Cost breakdown grouped by source.
    - `source` string, required: Usage source name.
    - `total_cost` number, required: Total cost for this source.
    - `total_tokens` integer, required: Total tokens for this source.
    - `prompt_tokens` integer, required: Prompt tokens for this source.
    - `completion_tokens` integer, required: Completion tokens for this source.
    - `record_count` integer, required: Number of usage records for this source.
  - `by_model` CostByModel[], required: Cost breakdown grouped by provider and model.
    - `provider` string, required: Provider of the model.
    - `model` string, required: Catalog name of the model.
    - `total_cost` number, required: Total cost for this model.
    - `total_tokens` integer, required: Total tokens for this model.
    - `prompt_tokens` integer, required: Prompt tokens for this model.
    - `completion_tokens` integer, required: Completion tokens for this model.
    - `record_count` integer, required: Number of usage records for this model.
  - `timeseries` CostTimeseriesPoint[], required: Daily cost timeseries across the window.
    - `date` string, required: Date of the data point (YYYY-MM-DD).
    - `cost` number, required: Cost incurred on this date.
    - `tokens` integer, required: Tokens consumed on this date.
    - `record_count` integer, required: Number of usage records on this date.

## Other responses

- `400`: Custom granularity requires both date_start and date_end.
- `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)