Get usage summary

GET

/v1/usage

const url = 'https://example.com/v1/usage';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Return aggregated usage for the calling org over a time range.

Pass either period=current_month (or previous_month) for convenience, or an explicit period_start / period_end pair. The two modes are mutually exclusive.

Authorizations

ApiKey

Parameters

Query Parameters

period

Any of:

string
null

string

Allowed values: current_month previous_month

Convenience period selector; mutually exclusive with explicit range.

period_start

Any of:

string
null

string format: date-time

ISO-8601 UTC. Must be paired with period_end.

period_end

Any of:

string
null

string format: date-time

ISO-8601 UTC. Must be paired with period_start.

Responses

200

Successful Response

application/json

UsageSummary

Aggregated usage; returned by GET /v1/usage.

object

billable_seconds

required

Total billable seconds across all sessions in the window.

integer

by_quality

billable_seconds per quality tier. Forward-compatible breakdown — additional by_* slices may appear over time.

object

key

additional properties

integer

period_end

required

Exclusive end of the aggregated window. Matches the period_end query argument.

string format: date-time

period_start

required

Inclusive start of the aggregated window. Matches the period_start query argument.

string format: date-time

sessions

required

Number of sessions that contributed usage in the window.

integer

Example

{
  "billable_seconds": 14280,
  "by_quality": {
    "pro": 2280,
    "standard": 12000
  },
  "period_end": "2026-05-25T19:00:00Z",
  "period_start": "2026-05-01T00:00:00Z",
  "sessions": 42
}

400

Invalid period / range.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}

401

Missing or invalid API key.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}

422

Request body or parameters failed validation.

application/json

ApiErrorEnvelope

Wire format for every non-2xx public API response.

object

error

required

ApiError

Concrete error returned inside ApiErrorEnvelope.error.

object

code

required

Stable machine-readable subcode (lower_snake_case). SDKs should switch on this, not message.

string

message

required

Human-readable summary. Not stable; do not parse.

string

param

Any of:

string
null

string

request_id

required

Echo of the X-Request-Id response header for support.

string

type

required

ErrorType

Top-level error categories. Maps roughly to HTTP status.

code (a free-form lower_snake_case string on ApiError) is the machine-readable subcode SDKs should switch on; type is the broad category.

string

Allowed values: invalid_request authentication permission not_found conflict unprocessable rate_limit quota_exceeded internal service_unavailable

Example

{
  "error": {
    "code": "transport.unsupported",
    "message": "transport.type=pipecat is reserved and not yet available",
    "param": "transport.type",
    "request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
    "type": "invalid_request"
  }
}