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

# List runs

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

Your organization's runs, newest first, one page at a time. The filters combine.

A run is one model inference. A successful decisions request is recorded as a run, which can take a moment to appear in this list, and under heavy load may not be recorded. A decisions request that fails before its input reaches the model, including every request rejected with a `4xx` status, has none.

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

## Authentication

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

## Request

### Query parameters

- `page_size` (integer, optional, default: 50) — How many runs to return.
- `cursor` (string, optional) — The `next_cursor` of the previous page. Pass it back unchanged, with the same filters as the request that returned it.
- `user_id` (string, optional) — Only runs made by this user.
- `status` (enum, optional) — Only runs with this status.
  - Allowed values: `ended`, `errored`
- `started_before` (datetime, optional) — Only runs that started before this time, in RFC 3339 format.
- `started_after` (datetime, optional) — Only runs that started at or after this time, in RFC 3339 format. Consecutive time ranges that share a boundary neither skip a run nor return one twice.

## Response

### 200

One page of runs.

- `runs` (list of RunSummary, required) — The runs, newest first.
- `next_cursor` (string, optional) — Absent on the last page. Pass it back as `cursor` for the next one.

## Errors

### 400 Bad Request Error

A query parameter needs correcting. `code` says which.

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

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

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

### RunSummary

One model inference, as the list returns it.

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

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

## Examples

**Response**

```json
{
  "runs": [
    {
      "run_id": "019a1f52-3c47-7f80-b1d9-6a2e4c8f0d37",
      "user_id": "8d3f4a1e-6b2c-4f7d-9e0a-1b2c3d4e5f60",
      "status": "ended",
      "started_at": "2026-10-26T17:09:02.114Z",
      "ended_at": "2026-10-26T17:09:04.538Z",
      "received": {
        "file_bytes": 2880044,
        "input_tokens": 7830
      }
    },
    {
      "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
      }
    },
    {
      "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
      }
    }
  ],
  "next_cursor": "eyJiZWZvcmUiOiIwMTlhMWYzYyJ9"
}
```