> This page is for Audio Decisions. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://dev.hume.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server. # Runs **A run is the record of one model inference.** Each request that reaches the model is recorded as a run, which can take a moment to appear. Under heavy load a run may not be recorded. The run endpoints return a run's status, when it started and ended and the request it evaluated. Its `received` field holds the size of the audio file and the input tokens the run was billed. Answers come only from the decisions response, so store the answers you need.
Endpoint Returns
[`GET /v0/decisions/run`](/audio-decisions/reference/runs/list) Paginated list of your organization's runs.
[`GET /v0/decisions/run/{run_id}`](/audio-decisions/reference/runs/get) One run: its status and the request it evaluated.
## Run IDs A run's `run_id` is the `run_id` in the response to its decisions request. The run can take a moment to appear: until it does, getting it returns `404` and listing runs leaves it out. Keep the `run_id` from each response, since under heavy load a run may not be recorded. A request that fails before its input reaches the model, including every request rejected with a `4xx` status, has no run. Error bodies carry a `request_id` but no `run_id`; quote the `request_id` when contacting support. Runs are scoped to your organization. A run in another organization returns `404`, the same as a run that does not exist or an ID that is not a UUID. ## Run status
Status Description
`ended` The run returned answers.
`errored` The run returned no answers, because inference failed or the client closed the connection first.
## Listing runs `GET /v0/decisions/run` returns your organization's runs, newest first. The filters combine, so the request below returns the runs that errored on October 26, 2026. #### cURL ```bash maxLines={0} curl -G https://api.cloud.hume.ai/v0/decisions/run \ -H "X-Hume-Api-Key: $HUME_API_KEY" \ -d status=errored \ -d started_after=2026-10-26T00:00:00Z \ -d started_before=2026-10-27T00:00:00Z ``` #### Python ```python maxLines={0} from datetime import datetime, timezone from hume_audio_decisions import DecisionsClient client = DecisionsClient() page = client.runs.list( status="errored", started_after=datetime(2026, 10, 26, tzinfo=timezone.utc), started_before=datetime(2026, 10, 27, tzinfo=timezone.utc), ) print(page.model_dump_json(indent=2)) ``` #### TypeScript ```typescript maxLines={0} import { DecisionsClient } from "@humeai/audio-decisions"; const client = new DecisionsClient(); const page = await client.runs.list({ status: "errored", startedAfter: new Date("2026-10-26T00:00:00Z"), startedBefore: new Date("2026-10-27T00:00:00Z"), }); console.log(JSON.stringify(page, null, 2)); ``` To send these requests from this page, open a panel and enter your API key. ### Request GET [https://api.cloud.hume.ai/v0/decisions/run](https://api.cloud.hume.ai/v0/decisions/run) ```curl curl https://api.cloud.hume.ai/v0/decisions/run \ -H "X-Hume-Api-Key: " ``` ```typescript import { DecisionsClient } from "@humeai/audio-decisions"; async function main() { const client = new DecisionsClient({ apiKey: "YOUR_API_KEY_HERE", }); await client.runs.list({}); } main(); ``` ```python from hume_audio_decisions import DecisionsClient client = DecisionsClient( api_key="YOUR_API_KEY_HERE", ) client.runs.list() ``` **`page_size`** — default: 50 How many runs to return, from 1 to 200. --- **`cursor`** The `next_cursor` of the previous page. See [Pagination](#pagination). --- **`user_id`** Only runs made by this user. --- **`status`** Only runs with this status: `ended` or `errored`. --- **`started_after`** Only runs that started at or after this time, in RFC 3339 format. --- **`started_before`** Only runs that started before this time, in RFC 3339 format. --- `started_after` includes its boundary and `started_before` excludes it, so consecutive time windows that share a boundary neither skip a run nor return one twice. #### 200 OK ```json { "runs": [ { "run_id": "019a1f50-a6e2-7b13-8c5f-3d9e1a7b4c20", "user_id": "3b7e9c2a-5d1f-4a8e-b6c0-7f2d1e4a9b35", "status": "errored", "started_at": "2026-10-26T17:06:40.207Z", "ended_at": "2026-10-26T17:06:40.981Z", "received": { "file_bytes": 164524 } } ], "next_cursor": "eyJiZWZvcmUiOiIwMTlhMWY1MCJ9" } ``` **`run_id`** The run's ID. See [Run IDs](#run-ids). --- **`user_id`** The Hume user who made the run. --- **`status`** See [Run status](#run-status). --- **`started_at, ended_at`** When the run started and ended. --- **`received.file_bytes`** The size of the audio file in the request's `file` part, in bytes. --- **`received.input_tokens`** The input tokens the run was billed: the same value as `received.input_tokens` in its decisions response. Absent for a run that was not billed. --- ## Pagination The list endpoint returns one page at a time. Every page but the last carries a `next_cursor`; on the last page the field is absent. Pass it back unchanged as `cursor`, with the same filters, to fetch the next page. A cursor the endpoint did not issue is rejected with `invalid_request`. ## Getting a run `GET /v0/decisions/run/{run_id}` returns the fields of the list, plus the `request` part the run evaluated. #### cURL ```bash maxLines={0} curl https://api.cloud.hume.ai/v0/decisions/run/019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03 \ -H "X-Hume-Api-Key: $HUME_API_KEY" ``` #### Python ```python maxLines={0} from hume_audio_decisions import DecisionsClient client = DecisionsClient() run = client.runs.get("019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03") print(run.model_dump_json(indent=2)) ``` #### TypeScript ```typescript maxLines={0} import { DecisionsClient } from "@humeai/audio-decisions"; const client = new DecisionsClient(); const run = await client.runs.get({ runId: "019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03", }); console.log(JSON.stringify(run, null, 2)); ``` ### Request GET [https://api.cloud.hume.ai/v0/decisions/run/\{run_id}](https://api.cloud.hume.ai/v0/decisions/run/\{run_id}) ```curl curl https://api.cloud.hume.ai/v0/decisions/run/019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03 \ -H "X-Hume-Api-Key: " ``` ```typescript import { DecisionsClient } from "@humeai/audio-decisions"; async function main() { const client = new DecisionsClient({ apiKey: "YOUR_API_KEY_HERE", }); await client.runs.get({ runId: "019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03", }); } main(); ``` ```python from hume_audio_decisions import DecisionsClient client = DecisionsClient( api_key="YOUR_API_KEY_HERE", ) client.runs.get( run_id="019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03", ) ``` #### 200 OK ```json { "run_id": "019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03", "user_id": "8d3f4a1e-6b2c-4f7d-9e0a-1b2c3d4e5f60", "status": "ended", "started_at": "2026-10-26T17:04:11.380Z", "ended_at": "2026-10-26T17:04:13.912Z", "received": { "file_bytes": 4320044, "input_tokens": 11234 }, "request": { "context": "A simulated test call in which a voice AI agent helps a caller reschedule an appointment. Both voices are synthetic, and the agent speaks first.", "questions": { "talks_over_caller": { "type": "noul", "instructions": "Does the agent talk over the caller?" }, "agent_naturalness": { "type": "score", "instructions": "How natural does the agent sound?", "criteria": ["Not at all", "2", "3", "4", "Extremely"] } } } } ``` **`request`** The `request` part the run evaluated: its `context` and `questions`, as sent. The run does not include the audio or the answers. --- ## Errors The run endpoints return the error body described in [Errors](/audio-decisions/docs/errors). A `401`, a `429` and a `404` for a path or method the API does not serve are answered by [Hume's API gateway](/audio-decisions/docs/errors#gateway-errors), so their body has a `message` but no `code`.
Status Code Description
400 `invalid_request` A query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. Sent by the list endpoint.
401 No code The request carried no valid API key. See [Authentication](/audio-decisions/docs/authentication) .
403 `forbidden` The credential does not grant access to this API. Contact support to request access.
404 `not_found` No run with this ID exists in your organization. Sent by the get endpoint.
404 No code No endpoint exists at this path, or the endpoint does not accept this HTTP method.
429 No code The organization sent more than 60 requests in a minute. See [Limits](/audio-decisions/docs/limits#rate-limits) . Wait the number of seconds in the `Retry-After` header, then retry.
500 `internal_error` The server failed while serving the request. Retry it. If the failure recurs, contact support with the `request_id` .
503 `server_busy` The service is at capacity. Wait the number of seconds in the `Retry-After` header, then retry.
## Next steps #### [Errors](/audio-decisions/docs/errors) Learn the error body and every code the endpoints return.