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

# Get run

GET https://api.cloud.hume.ai/v0/decisions/run/{run_id}

The run's status, when it started and ended, the audio it received, and the request it evaluated. The run does not include the answers.

Reference: https://dev.hume.ai/audio-decisions/reference/runs/get

## Authentication

- `X-Hume-Api-Key` header (required) — API Key authentication via header

## Request

### Path parameters

- `run_id` (string, required) — The run's ID: the `run_id` of a decisions response. An ID that is not a UUID returns `404`, as an unknown one does.

## Response

### 200

The run.

- `run_id` (string, required) — The run's ID: the `run_id` of a decisions response.
- `user_id` (string, required) — The ID of the Hume user who made the run.
- `status` (enum, required) — How a run ended: `ended` if it returned answers, and `errored` if it returned none because inference failed or the client closed the connection first.
  - Allowed values: `ended`, `errored`
- `started_at` (datetime, required) — When the run started.
- `ended_at` (datetime, required) — When the run ended.
- `received` (RunReceived, required) — The `file` part a run received, and the input tokens it was billed.
- `request` (DecisionsRequest, required) — The `request` part the run evaluated: its `context` and `questions`, as sent.

## Errors

### 401 Unauthorized Error

The request carried no valid credential. Check the API key you sent.

- `message` (string, required) — A description of the problem for a person.
- `request_id` (string, optional) — The ID of the request. A `401` carries it only when an API key was rejected, and a `429` never does.

### 403 Forbidden Error

The credential does not grant access to this API. Contact support to request access.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 404 Not Found Error

No run with this ID exists in your organization. A run can take a moment to appear after its decisions response.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 429 Too Many Requests Error

The request exceeds a rate limit for the account. Hume's API gateway answers it before the request reaches the service, so its body has no `code`. Retry after the number of seconds in the `Retry-After` header.

- `message` (string, required) — A description of the problem for a person.
- `request_id` (string, optional) — The ID of the request. A `401` carries it only when an API key was rejected, and a `429` never does.

### 500 Internal Server Error

An unexpected error occurred on the server. Retry the request, and if it keeps failing, contact support with the `request_id`.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 503 Service Unavailable Error

The service is at capacity. Retry after the number of seconds in the `Retry-After` header.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

## Types

### RunReceived

The `file` part a run received, and the input tokens it was billed.

- `file_bytes` (integer, required) — The size of the `file` part as sent, in bytes.
- `input_tokens` (integer, optional) — The input tokens the run was billed: the decisions response's `received.input_tokens`. Absent for a run that was not billed.

### DecisionsRequest

The `request` part: the questions to answer and optional context.

- `questions` (map from string to Question, required) — The questions to answer: at most 20 `noul`, `choice` and `score` questions together, and at most 5 `span` questions. Each key is a question ID you choose, such as `agent_tone`, and can be any non-empty string of up to 256 characters. The response returns each answer under the same ID.
- `context` (string, optional) — Background information the model considers alongside the audio, such as the setting or who is speaking.

### Question

A question. `type` names its primitive, which determines the question's options and the structure of its answer.

- `type`: `noul` (noul question)
  - `instructions` (string, required) — The question, written in natural language.
  - `criteria` (NoulCriteria, optional) — Guidance on what counts as a yes or a no answer. The model reads it along with the question.
- `type`: `choice` (choice question)
  - `criteria` (list of Criterion, required) — The options, presented to the model in the order listed. A question with fewer than two options or more than 20, or with duplicate names, is rejected with `question_invalid`.
  - `instructions` (string, required) — The question, written in natural language.
- `type`: `score` (score question)
  - `criteria` (list of string, required) — The levels, ordered from lowest to highest and numbered from 0. The model reads each level's text, and the answer's `legend` returns it. A question with fewer than two levels or more than 10, or with duplicate levels, is rejected with `question_invalid`.
  - `instructions` (string, required) — The question, written in natural language.
- `type`: `span` (span question)
  - `instructions` (string, required) — The question, written in natural language.

### NoulCriteria

Guidance on what counts as a yes or a no answer. The model reads it along with the question.

- `true` (string, optional) — What counts as a yes answer.
- `false` (string, optional) — What counts as a no answer.

### Criterion

One option of a `choice` question. The model reads the option's `name` and, when it has one, its `description`. Answers are keyed by `name`.

- `name` (string, required) — The option, unique within the question. The model reads it and answers are keyed by it, so make it short and self-explanatory.
- `description` (string, optional) — More detail on when the option applies, which the model reads along with the name.

## Examples

**Response**

```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": 11683
  },
  "request": {
    "questions": {
      "agent_glitches": {
        "type": "span",
        "instructions": "Where does the agent glitch, slur or sound robotic?"
      },
      "agent_naturalness": {
        "type": "score",
        "criteria": [
          "Not at all",
          "2",
          "3",
          "4",
          "Extremely"
        ],
        "instructions": "How natural does the agent sound?"
      },
      "agent_tone": {
        "type": "choice",
        "criteria": [
          {
            "name": "warm",
            "description": "Warm and friendly toward the caller"
          },
          {
            "name": "neutral",
            "description": "Polite but impersonal"
          },
          {
            "name": "curt",
            "description": "Short or dismissive with the caller"
          }
        ],
        "instructions": "Which best describes the tone of the agent?"
      },
      "talks_over_caller": {
        "type": "noul",
        "instructions": "Does the agent talk over the caller?"
      }
    },
    "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."
  }
}
```