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.
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.
Headers
AuthorizationRequiredBearer <SONIOX_API_KEY>Query parameters
start_timeRequiredstringStart 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_timeRequiredstringEnd 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).
limitintegerMaximum number of usage log entries to return.
1000Minimum: 1Maximum: 1000sortstringSort 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.
"end_time_asc"Accepted values: "end_time_asc" | "end_time_desc"cursorstringPagination 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_cursorstringA 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_timenot parseable as ISO 8601,end_timenot strictly afterstart_time, the window between them exceeds 31 days, orcursordoes not match the suppliedstart_time/end_time/sort.invalid_cursor: Thecursorparameter is invalid. Omitcursorto 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. Themessagedescribes 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"
}