Read what one conversation cost, broken down by model

curl --request GET \
  --url https://api.example.com/v1/sessions/{sessionId}/usage \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sessions/{sessionId}/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/sessions/{sessionId}/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
  "groupBy": "model",
  "rows": [
    {
      "group": "claude-opus-4",
      "inputTokens": 120000,
      "outputTokens": 8000,
      "costUsd": 2.4
    },
    {
      "group": "claude-sonnet-4-5",
      "inputTokens": 2400000,
      "outputTokens": 130000,
      "costUsd": 9.15
    }
  ]
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Read what one conversation cost, broken down by model

What this conversation has spent, one row per model it was billed under. The session resource already reports the same money as two scalars — usage.costUsd over the whole conversation, and cacheSpend, which DECOMPOSES part of that same figure rather than adding to it. This is the third view of those same dollars and adds nothing to them either: a conversation that ran on three models reports one number there and says which model spent it here, and the rows sum to that number. The model is the one a round was BILLED under, which is the model that answered and not the one that was asked for. A round this host cannot price contributes its tokens and no dollars, so its group reports costComplete false and its costUsd is a floor. A colleague refused the transcript is refused this.

GET

sessions

{sessionId}

usage

Read what one conversation cost, broken down by model

curl --request GET \
  --url https://api.example.com/v1/sessions/{sessionId}/usage \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sessions/{sessionId}/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/sessions/{sessionId}/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
  "groupBy": "model",
  "rows": [
    {
      "group": "claude-opus-4",
      "inputTokens": 120000,
      "outputTokens": 8000,
      "costUsd": 2.4
    },
    {
      "group": "claude-sonnet-4-5",
      "inputTokens": 2400000,
      "outputTokens": 130000,
      "costUsd": 9.15
    }
  ]
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Authorizations

Authorization

string

header

required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Path Parameters

sessionId

string<uuid>

required

The session's id.

Query Parameters

cursor

string

Opaque pagination cursor from a previous page's nextCursor or prevCursor.

Maximum string length: 1024

limit

integer

default:25

Maximum items per page.

Required range: 1 <= x <= 100

Response

One page of the conversation's consumption.

One conversation's consumption, one page of it, grouped by the model each round was billed under and ordered by model name ascending.

sessionId

string<uuid>

required

groupBy

enum<string>

required

The dimension these rows are grouped by. model is the only one a single conversation has; it is echoed so a client reads the same envelope here as on the period report.

Available options:

model

rows

object[]

required

Show child attributes

nextCursor

string

Pass as cursor for the next page. Absent on the last page.

Overview

Host

Sessions

Messages

Events

Lanes

Monitors

Agents

Skills and commands

Permissions

Peers

Packages

Extensions

Workflows

Schedules

Providers

Records

Environments

Sharing

Refinements

Platform

Error handling

Read what one conversation cost, broken down by model

Authorizations

Path Parameters

Query Parameters

Response