Soniox
OtherAPI ReferenceOther

Get usage logs

Returns per-request usage log entries for the project. The project is implied by the API key used for authentication. Filters by request end time. The window between start_time and end_time must not exceed 31 days. start_time must not be earlier than 91 days ago.

GET
https://api.soniox.com/v1/usage-logs

Returns per-request usage log entries for the project. The project is implied by the API key used for authentication. Filters by request end time. The window between start_time and end_time must not exceed 31 days. start_time must not be earlier than 91 days ago.

Headers

AuthorizationRequiredBearer <SONIOX_API_KEY>

Query parameters

start_timeRequiredstring

Start of the time window (inclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. 2026-04-28T09:00:00Z).

end_timeRequiredstring

End of the time window (exclusive). Filters by request end time. Must be an ISO 8601 timestamp in UTC (e.g. 2026-04-28T09:00:00Z).

limitinteger

Maximum number of usage log entries to return.

Default: 1000Minimum: 1Maximum: 1000
sortstring

Sort order by end_time.Use end_time_desc to get the most recent entries first. When paginating, pass the same sort value alongside the cursor.

Default: "end_time_asc"Accepted values: "end_time_asc" | "end_time_desc"
cursorstring

Pagination cursor for the next page of results.

Response

200

Per-request usage log entries.

usage_logsRequiredarray<object>

Per-request usage log entries ordered by end_time, uuid (per sort).

next_page_cursorstring

A pagination token that references the next page of results. When more data is available, this field contains a value to pass in the cursor parameter of a subsequent request. When null, no additional results are available.

Errors

Per-request usage log entries.

{
  "usage_logs": [
    {
      "uuid": "0d1e2f3a-4b5c-6d7e-8f90-1234567890ab",
      "request_scope": "api",
      "client_reference_id": "some_internal_id",
      "model": "stt-async-v3",
      "start_time": "2026-04-28T09:00:00Z",
      "end_time": "2026-04-28T09:00:12Z",
      "input_text_tokens": 42,
      "input_audio_tokens": 12345,
      "input_audio_duration_ms": 12000,
      "output_text_tokens": 678,
      "output_audio_tokens": 256,
      "output_audio_duration_ms": 4500,
      "cost_usd": "0.0081000000",
      "input_cost_usd": "0.0011000000",
      "input_text_cost_usd": "0.0001000000",
      "input_audio_cost_usd": "0.0010000000",
      "output_cost_usd": "0.0070000000",
      "output_text_cost_usd": "0.0050000000",
      "output_audio_cost_usd": "0.0020000000"
    }
  ],
  "next_page_cursor": "cursor_or_null"
}

Invalid request.

Error types:

  • invalid_request: A query parameter is missing or invalid. Common causes: start_time / end_time not parseable as ISO 8601, end_time not strictly after start_time, the window between them exceeds 31 days, or cursor does not match the supplied start_time / end_time / sort.
  • invalid_cursor: The cursor parameter is invalid. Omit cursor to start pagination from the beginning.

{
  "status_code": 400,
  "error_type": "invalid_request",
  "message": "Your request did not pass validation. One or more fields in the request body are missing or have invalid values. See `validation_errors` for the specific field and retry with corrected values.",
  "validation_errors": [
    {
      "error_type": "value_error",
      "location": "query.payload",
      "message": "The period between start_time and end_time must not exceed 31 days."
    }
  ],
  "request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
  "more_info": "https://soniox.com/docs/api-reference/errors#invalid-request"
}

Authentication error.

{
  "status_code": 401,
  "error_type": "unauthenticated",
  "message": "Incorrect API key provided. You can get an API key at https://console.soniox.com",
  "validation_errors": [],
  "request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
  "more_info": "https://soniox.com/docs/api-reference/errors#unauthenticated"
}

Rate / capacity limit exceeded.

Error types:

  • limit_exceeded: The caller hit a per-minute request rate or other capacity limit. The message describes which limit was hit.

{
  "status_code": 429,
  "error_type": "limit_exceeded",
  "message": "Requests per minute limit for usage logs has been exceeded for your organization.",
  "validation_errors": [],
  "request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
  "more_info": "https://soniox.com/docs/api-reference/errors#limit-exceeded"
}

Internal server error.

{
  "status_code": 500,
  "error_type": "internal_error",
  "message": "The server encountered an error. Please try again. If the issue persists contact support@soniox.com.",
  "validation_errors": [],
  "request_id": "3d37a3bd-5078-47ee-a369-b204e3bbedda",
  "more_info": "https://soniox.com/docs/api-reference/errors#internal-error"
}

Get concurrent streams history GET

Returns historical concurrent stream counts for the project, aggregated per period. The project is implied by the API key used for authentication. Region-scoped. Every aggregation period in the requested window is returned, with no gaps. Periods with no recorded activity have every field set to `0`.

Get usage summary GET

Returns daily cost and activity for the project, broken down per model and summed across all models. The project is implied by the API key used for authentication. Usage is aggregated by whole UTC day. The window is half-open, `[start_time, end_time)`, and a day is included when the window covers any part of it, so an `end_time` exactly at midnight excludes that day. The window must not cover more than 366 UTC days.