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.

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

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 -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

To send these requests from this page, open a panel and enter your API key.

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.

{
  "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"
}

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 https://api.cloud.hume.ai/v0/decisions/run/019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03 \
  -H "X-Hume-Api-Key: $HUME_API_KEY"

{
  "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"]
      }
    }
  }
}

Errors

The run endpoints return the error body described in 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, so their body has a message but no code.

Next steps