Skip to content
KataraKatara documentation

Read what an organization was charged in a period

GET
/katara/v1/orgs/{org_id}/statements
curl --request GET \
  --url 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/statements?from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z' \
  --cookie katara_session=<katara_session>

Requires current billing:read permission. Billing is its own role: an administrator who can change what the agents do is not thereby entitled to what the organization spent. The figures are re-derived from the ledger on every read rather than stored, so the same period always answers the same way and a correction cannot leave a stale total behind. Lines are grouped by environment, usage class and purpose; totals are per usage class and never across them, because simulation credits, Test Compute and Live money are not the same money. The integrity digest is taken over the body and can be recomputed by a holder without this API. Periods longer than 366 days are refused.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Query Parameters

Section titled “Query Parameters”
from
required
string format: date-time

Start of the period, inclusive, as an RFC 3339 moment.

to
required
string format: date-time

End of the period, exclusive, as an RFC 3339 moment. Both ends are required: a default window would decide which month was meant.

Responses

Section titled “Responses”

200

Section titled “200”

What the organization was charged in the period.

Media typeapplication/json

What an organization was charged in one period, grouped by environment, usage class, purpose and the price version that priced it. Totals are per usage class and never across them: simulation credits, Test Compute and Live money are not the same money. The figures are re-derived from the ledger on every read, so the same period always answers the same way.

object
schema_version
required
integer
Allowed value: 2
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
period_start
required
string format: date-time
period_end
required
string format: date-time
lines
required
Array<object>
<= 5000 items
object
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
mode
required
string
Allowed values: test live
usage_class
required
string
Allowed values: simulation test_compute live
purpose
required
string
Allowed values: inference tool service sandbox evaluation
asset
required
string
Allowed value: CREDIT_ATOMIC
scale
required
integer
Allowed value: 9
tariff_id
required
One of:
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
tariff_version
required
One of:
integer
>= 1 <= 9007199254740991
charged
required
string
/^(0|[1-9][0-9]{0,17})$/
actions
required
integer
<= 9007199254740991
totals
required
Array<object>
<= 3 items
object
usage_class
required
string
Allowed values: simulation test_compute live
asset
required
string
Allowed value: CREDIT_ATOMIC
scale
required
integer
Allowed value: 9
charged
required
string
/^(0|[1-9][0-9]{0,17})$/
actions
required
integer
<= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
Example
{
  "schema_version": 2,
  "lines": [
    {
      "mode": "test",
      "usage_class": "simulation",
      "purpose": "inference",
      "asset": "CREDIT_ATOMIC",
      "scale": 9
    }
  ],
  "totals": [
    {
      "usage_class": "simulation",
      "asset": "CREDIT_ATOMIC",
      "scale": 9
    }
  ]
}

default

Section titled “default”

Request rejected or unavailable.

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}