---
title: "What one session spent"
method: GET
path: "/api/v2/projects/{projectId}/sessions/{sessionId}/usage"
tags: ["Usage"]
---

# What one session spent

`GET /api/v2/projects/{projectId}/sessions/{sessionId}/usage`

## Request

- Base URL: `https://davinci-app.com`
- URL: `https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/usage`
- Auth: HTTP bearer

What a single session's agent run cost. This is the granularity to use when
you want to know the price of a specific piece of work rather than a month of
it.

A run still in progress will under-report until its last interval is flushed,
so read `asOf` — or read this after `waitUntilDone` returns.

## Query parameters

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

## Response `200`

Usage totals for the session.

- 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`).
- `404`: No such session, it belongs to another user, or it belongs to a different project than the one in the path. Error code is `SESSION_NOT_FOUND`.
- `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`: 6 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 `404`
  - …2 more
- **2026-09-15** (v2) `48948af37797`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/projects/:projectId/sessions/:sessionId/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)