---
title: "Public Get Billing Spend"
method: GET
path: "/v1/billing/spend"
tags: ["public-api"]
---

# Public Get Billing Spend

`GET /v1/billing/spend`

## Request

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

Spend and usage by UTC day and by model (TRA-1193).

The response covers every request the team sent through the gateway
between `start` and `end`, priced at the team's rates. Each day and
each model carries request and token counts alongside its `cost_usd`.
The window is half-open (`end` is excluded). It may cover at most 31
days, one calendar month, and it may not start before the year of
usage the gateway keeps.

`model` narrows both breakdowns to one slug. The gateway groups usage
by the model it routed to, so the slug to send is one the `models`
list names. Traffic sent under an alias of that model is counted with
it, and a filter on the alias itself finds nothing. A request that a
fallback model answered stays under the model you called, priced at
the fallback model's own rates, which is how it is invoiced.

`prompt_tokens` includes `cached_prompt_tokens`, and the gateway prices
the difference as fresh input. These are the Billing page's figures,
built the way the invoice is: token models at your rates, and a
dedicated GPU model at each day's invoice figure (the monthly base
prorated by day plus overage GPU-minutes). Models you pay a provider
for directly are not priced, and a GPU day the nightly billing cycle
has not recorded yet (today) is not priced either; both show as
requests outside `priced_request_count`.

## Query parameters

- `start` string, date, nullable: The first UTC day of the window. The default is 30 days before `end`.
- `end` string, date, nullable: The first UTC day after the window. The default is tomorrow, which puts today inside the window.
- `model` string, nullable: One model slug, as the /v1/billing/spend `models` list names it. The default is every model.

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- BillingSpendResponse: Priced usage over a window, by UTC day and by model. Priced by the gateway the way the invoice is built: token models at the team's rates on the metered quantities, and dedicated GPU models at each day's invoice figure. `start` and `end` are the half-open window's UTC instants. The Billing page reads this over its 30-day window, and GET /v1/billing/spend serves it over a caller's window (TRA-1193).
  - `start` string, required
  - `end` string, required
  - `days` BillingSpendDay[], required
    - `date` string, required
    - `request_count` integer, required
    - `priced_request_count` integer, required
    - `prompt_tokens` integer, required
    - `cached_prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `cost_usd` string, nullable, required
    - `pricing_status` 'priced' | 'unavailable', required
  - `models` BillingSpendModel[], required
    - `model` string, required
    - `request_count` integer, required
    - `priced_request_count` integer, required
    - `prompt_tokens` integer, required
    - `cached_prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `cost_usd` string, nullable, required
    - `pricing_status` 'priced' | 'unavailable', required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-09** `26478f75ef09`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trainloop/apis/trainloop-api/changes/v1/billing/spend/get.md)

---

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