---
title: "The session's billed usage, newest first [read]"
method: GET
path: "/sessions/{id}/usage"
---

# The session's billed usage, newest first \[read\]

`GET /sessions/{id}/usage`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}/usage`
- Auth: HTTP bearer

Totals plus one row per billed event — model turns, runtime, capability and connector calls — with the token breakdown, list and billed dollars, basis and duration. `limit` (default 50) pages with an opaque `cursor`; keep following `cursor` until it is null. A row whose `coveredBy` is `subscription` ran on the reader's own Claude or ChatGPT plan: `listCostUsd` is what it was worth, `billedCostUsd` is zero. Dollar amounts here are numbers in USD, not the `{amount, currency}` cents object used elsewhere.

## Path parameters

- `id` string, required

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

OK

- SessionUsage
  - `session` string, required: The session's public id (sess_…)
  - `totals` object, required: Summed over the whole session, not just this page. `durationComplete` is false while a turn is still running. `tokenCostsUsd` is only present when every model charge carried its original breakdown.
    - `listCostUsd` number
    - `billedCostUsd` number
    - `inputTokens` integer
    - `outputTokens` integer
    - `cachedInputTokens` integer
    - `cacheCreationTokens` integer
    - `modelBilledCostUsd` number
    - `runtimeCostUsd` number
    - `capabilityCallCostUsd` number
    - `connectorCallCostUsd` number
    - `turns` integer
    - `durationMs` integer
    - `durationComplete` boolean
    - `coveredBy` 'subscription' | 'null', nullable
    - `tokenCostsUsd` object, nullable
      - `input` number
      - `output` number
      - `cachedInput` number
      - `cacheCreation` number
  - `entries` SessionUsageEntry[], required
    - `kind` string, required
    - `at` string, date-time, required
    - `listCostUsd` number, nullable
    - `billedCostUsd` number, required
    - `coveredBy` 'subscription' | 'null', nullable: Why a metered turn was booked at $0, when that is known
    - `model` string, nullable
    - `provider` string, nullable
    - `basis` string, nullable
    - `durationMs` integer, nullable
    - `interrupted` boolean, nullable
    - `tokens` object, required
      - `input` integer
      - `output` integer
      - `cachedInput` integer
      - `cacheCreation` integer
  - `budget` object, nullable: The session's budget summary — the same shape as `budget` on Session — or null when it has none
  - `cursor` string, nullable, required: Pass as ?cursor= for the next page; null on the last

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 4 info
  - added the optional property `error/request_id` to the response with the `default` status
  - the response property `error` became required for the status `default`
  - the response property `error/code` became required for the status `default`
  - the response property `error/message` became required for the status `default`

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/usage/get.md)

---

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