---
title: "What you spent"
method: GET
path: "/api/v2/usage"
tags: ["Usage"]
---

# What you spent

`GET /api/v2/usage`

## Request

- Base URL: `https://davinci-app.com`
- URL: `https://davinci-app.com/api/v2/usage`
- Auth: HTTP bearer

Dollars and tokens charged to your account, optionally narrowed by project,
session, or time, and optionally broken down by model, project, session, or
day.

This reports your own usage. A project you share with collaborators returns
what *you* spent on it, not the project's total — what someone else spends is
their financial data, not the project's.

Reads are eventually consistent with a live run: the engine reports usage on
an interval, so check `asOf` before treating a total as final.

## Query parameters

- `projectId` string
- `sessionId` string
- `from` string, date-time
- `to` string, date-time
- `groupBy` 'model' | 'project' | 'session' | 'day'

## Response `200`

Usage totals for the scope, and the breakdown if one was asked for.

- UsageResponse
  - `scope` 'account' | 'project' | 'session', required: What the numbers cover, determined by the path you called.
  - `projectId` string: Present on the project and session reads. Always the bare id.
  - `sessionId` string, uuid: Present on the session read.
  - `asOf` string, date-time, nullable, required: When the newest counted event was recorded, or null when the scope holds none. This is the honest bound on freshness: the engine reports usage on an interval, so a run's last few seconds may not be included. Null means "nothing here", not "nothing yet" — a scope with no usage looks the same either way, and inventing a timestamp would hide that.
  - `totals` UsageTotals, required
    - `amountUsd` number, required: Dollars charged (USD), to six decimal places.
    - `promptTokens` integer, required
    - `completionTokens` integer, required
    - `reasoningTokens` integer, required: Thinking tokens, charged at the completion rate.
    - `cacheWriteTokens` integer, required
    - `cacheReadTokens` integer, required
    - `eventCount` integer, required: Charged calls counted. Not all of them are token-priced — image generation and web search are charged per call, so a non-zero `amountUsd` with zero tokens is normal rather than a gap.
  - `groupBy` 'model' | 'project' | 'session' | 'day': Echoed back when you asked for a breakdown.
  - `groups` UsageGroup[]: One entry per group, largest spend first — except `day`, which is chronological. Absent unless you passed `groupBy`.
    - `amountUsd` number, required: Dollars charged (USD), to six decimal places.
    - `promptTokens` integer, required
    - `completionTokens` integer, required
    - `reasoningTokens` integer, required: Thinking tokens, charged at the completion rate.
    - `cacheWriteTokens` integer, required
    - `cacheReadTokens` integer, required
    - `eventCount` integer, required: Charged calls counted. Not all of them are token-priced — image generation and web search are charged per call, so a non-zero `amountUsd` with zero tokens is normal rather than a gap.
    - `provider` string, nullable: Present when grouping by model.
    - `model` string, nullable: Present when grouping by model.
    - `projectId` string, nullable: Present when grouping by project.
    - `sessionId` string, nullable: Present when grouping by session.
    - `day` string, date-time, nullable: Midnight UTC of the day. Present when grouping by day.

## Other responses

- `400`: Invalid request. Error code is `INVALID_GROUP_BY` or `INVALID_RANGE`.
- `401`: No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request.
- `403`: Authenticated but not authorized. Either the acting user lacks the required resource permission, the key's scope ceiling excludes it, or the endpoint rejects this credential type (`CREDENTIAL_NOT_PERMITTED`).
- `429`: Request rate exceeded, either globally or for this key.
- `500`: Unexpected server error.

## Changes

- **2026-10-28** (v2) `0230867823db`: 2 breaking, 2 info
  - removed the required property `groups/items/allOf[#/components/schemas/UsageTotals]/credits` from the response with the `200` status
  - removed the required property `totals/credits` from the response with the `200` status
  - added the required property `groups/items/allOf[#/components/schemas/UsageTotals]/amountUsd` to the response with the `200` status
  - added the required property `totals/amountUsd` to the response with the `200` status
- **2026-09-15** (v2) `67c8b8616dbb`: 5 info
  - the `success` response property const value `false` was added for the status `400`
  - the `success` response property const value `false` was added for the status `401`
  - the `success` response property const value `false` was added for the status `403`
  - the `success` response property const value `false` was added for the status `429`
  - …1 more
- **2026-09-15** (v2) `48948af37797`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/usage/get.md)

---

[API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)