> This page is for Expression Measurement.

> 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/v1/expression/run

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

Reference: https://dev.hume.ai/expression-measurement/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.
- `user_id` (string, optional) — Only runs made by this user.
- `status` (enum, optional) — Only runs with this status.
  - Allowed values: `live`, `ended`, `errored`
- `mode` (enum, optional) — Only runs that reached the API this way.
  - Allowed values: `realtime`, `file`
- `endpoint` (enum, optional) — Only runs that measured this kind of media.
  - Allowed values: `audio`, `video`
- `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

Something in the request needs correcting: a malformed body or parameter, or a value the endpoint does not accept. `code` says which.

- `type` (enum, required)
  - Allowed values: `error`
- `code` (enum, required) — Identifies what went wrong. The HTTP status carried with it says how the request failed. Some of these names are also error codes of the realtime API, where they name the same kind of problem. **`400 Bad Request`**, something in the request needs correcting. - `message_invalid`: the multipart body could not be read, is missing its `file` part, or carries a part with another name. Audio takes exactly one `file` part; video takes one or more. File endpoints only. - `config_invalid`: the `config` part is not valid JSON, names a field the endpoint does not recognize, holds a value outside its range, or appears more than once. File endpoints only. - `audio_decode_failed`: the audio could not be decoded: a WAV file that is truncated or malformed, or at another sample rate, channel count or sample format, or with the extensible WAV header, or a file that is empty or is not a whole number of 16-bit samples. Audio only. - `image_decode_failed`: an image could not be decoded. Video only. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. Run endpoints only. **`403 Forbidden`** - `forbidden`: your organization is not permitted to use this endpoint. Contact support. File endpoints only. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization, or no endpoint exists at this path. **`405 Method Not Allowed`** - `method_not_allowed`: the endpoint does not accept this HTTP method. The `Allow` header lists the methods it does accept. **`413 Content Too Large`**, the request exceeds a size limit. - `audio_too_long`: the request body is over the size limit. Audio only. - `image_too_large`: the request body or one image is over the size limit, or an image has more pixels than the endpoint accepts. Video only. **`415 Unsupported Media Type`**, the media is in a format the endpoint does not accept. - `unsupported_media_type`: the audio is in a format the server recognizes but does not accept, such as MP3 or FLAC, or an image is not a JPEG. File endpoints only. **`500 Internal Server Error`** - `internal_error`: the server failed while serving the request. Retry it; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is too busy to serve the request now. Retry it after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `config_invalid`, `audio_decode_failed`, `image_decode_failed`, `invalid_request`, `forbidden`, `not_found`, `method_not_allowed`, `audio_too_long`, `image_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — What went wrong, for a person. Its wording may change; switch on `code`.
- `request_id` (string, required) — Identifies the request in Hume's records. Quote it when contacting support.

### 401 Unauthorized Error

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

- `message` (string, required) — What went wrong, for a person.
- `request_id` (string, optional) — Identifies the request. Sent only when an API key was rejected.

### 405 Method Not Allowed Error

The endpoint does not accept this HTTP method. The `Allow` header lists the methods it does accept.

- `type` (enum, required)
  - Allowed values: `error`
- `code` (enum, required) — Identifies what went wrong. The HTTP status carried with it says how the request failed. Some of these names are also error codes of the realtime API, where they name the same kind of problem. **`400 Bad Request`**, something in the request needs correcting. - `message_invalid`: the multipart body could not be read, is missing its `file` part, or carries a part with another name. Audio takes exactly one `file` part; video takes one or more. File endpoints only. - `config_invalid`: the `config` part is not valid JSON, names a field the endpoint does not recognize, holds a value outside its range, or appears more than once. File endpoints only. - `audio_decode_failed`: the audio could not be decoded: a WAV file that is truncated or malformed, or at another sample rate, channel count or sample format, or with the extensible WAV header, or a file that is empty or is not a whole number of 16-bit samples. Audio only. - `image_decode_failed`: an image could not be decoded. Video only. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. Run endpoints only. **`403 Forbidden`** - `forbidden`: your organization is not permitted to use this endpoint. Contact support. File endpoints only. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization, or no endpoint exists at this path. **`405 Method Not Allowed`** - `method_not_allowed`: the endpoint does not accept this HTTP method. The `Allow` header lists the methods it does accept. **`413 Content Too Large`**, the request exceeds a size limit. - `audio_too_long`: the request body is over the size limit. Audio only. - `image_too_large`: the request body or one image is over the size limit, or an image has more pixels than the endpoint accepts. Video only. **`415 Unsupported Media Type`**, the media is in a format the endpoint does not accept. - `unsupported_media_type`: the audio is in a format the server recognizes but does not accept, such as MP3 or FLAC, or an image is not a JPEG. File endpoints only. **`500 Internal Server Error`** - `internal_error`: the server failed while serving the request. Retry it; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is too busy to serve the request now. Retry it after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `config_invalid`, `audio_decode_failed`, `image_decode_failed`, `invalid_request`, `forbidden`, `not_found`, `method_not_allowed`, `audio_too_long`, `image_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — What went wrong, for a person. Its wording may change; switch on `code`.
- `request_id` (string, required) — Identifies the request in Hume's records. Quote it when contacting support.

### 500 Internal Server Error

The server failed while serving the request. Retry it; if it keeps failing, contact support, quoting the `request_id`.

- `type` (enum, required)
  - Allowed values: `error`
- `code` (enum, required) — Identifies what went wrong. The HTTP status carried with it says how the request failed. Some of these names are also error codes of the realtime API, where they name the same kind of problem. **`400 Bad Request`**, something in the request needs correcting. - `message_invalid`: the multipart body could not be read, is missing its `file` part, or carries a part with another name. Audio takes exactly one `file` part; video takes one or more. File endpoints only. - `config_invalid`: the `config` part is not valid JSON, names a field the endpoint does not recognize, holds a value outside its range, or appears more than once. File endpoints only. - `audio_decode_failed`: the audio could not be decoded: a WAV file that is truncated or malformed, or at another sample rate, channel count or sample format, or with the extensible WAV header, or a file that is empty or is not a whole number of 16-bit samples. Audio only. - `image_decode_failed`: an image could not be decoded. Video only. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. Run endpoints only. **`403 Forbidden`** - `forbidden`: your organization is not permitted to use this endpoint. Contact support. File endpoints only. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization, or no endpoint exists at this path. **`405 Method Not Allowed`** - `method_not_allowed`: the endpoint does not accept this HTTP method. The `Allow` header lists the methods it does accept. **`413 Content Too Large`**, the request exceeds a size limit. - `audio_too_long`: the request body is over the size limit. Audio only. - `image_too_large`: the request body or one image is over the size limit, or an image has more pixels than the endpoint accepts. Video only. **`415 Unsupported Media Type`**, the media is in a format the endpoint does not accept. - `unsupported_media_type`: the audio is in a format the server recognizes but does not accept, such as MP3 or FLAC, or an image is not a JPEG. File endpoints only. **`500 Internal Server Error`** - `internal_error`: the server failed while serving the request. Retry it; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is too busy to serve the request now. Retry it after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `config_invalid`, `audio_decode_failed`, `image_decode_failed`, `invalid_request`, `forbidden`, `not_found`, `method_not_allowed`, `audio_too_long`, `image_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — What went wrong, for a person. Its wording may change; switch on `code`.
- `request_id` (string, required) — Identifies the request in Hume's records. Quote it when contacting support.

### 503 Service Unavailable Error

The service is too busy to serve the request now. Retry it after the number of seconds in the `Retry-After` header.

- `type` (enum, required)
  - Allowed values: `error`
- `code` (enum, required) — Identifies what went wrong. The HTTP status carried with it says how the request failed. Some of these names are also error codes of the realtime API, where they name the same kind of problem. **`400 Bad Request`**, something in the request needs correcting. - `message_invalid`: the multipart body could not be read, is missing its `file` part, or carries a part with another name. Audio takes exactly one `file` part; video takes one or more. File endpoints only. - `config_invalid`: the `config` part is not valid JSON, names a field the endpoint does not recognize, holds a value outside its range, or appears more than once. File endpoints only. - `audio_decode_failed`: the audio could not be decoded: a WAV file that is truncated or malformed, or at another sample rate, channel count or sample format, or with the extensible WAV header, or a file that is empty or is not a whole number of 16-bit samples. Audio only. - `image_decode_failed`: an image could not be decoded. Video only. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. Run endpoints only. **`403 Forbidden`** - `forbidden`: your organization is not permitted to use this endpoint. Contact support. File endpoints only. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization, or no endpoint exists at this path. **`405 Method Not Allowed`** - `method_not_allowed`: the endpoint does not accept this HTTP method. The `Allow` header lists the methods it does accept. **`413 Content Too Large`**, the request exceeds a size limit. - `audio_too_long`: the request body is over the size limit. Audio only. - `image_too_large`: the request body or one image is over the size limit, or an image has more pixels than the endpoint accepts. Video only. **`415 Unsupported Media Type`**, the media is in a format the endpoint does not accept. - `unsupported_media_type`: the audio is in a format the server recognizes but does not accept, such as MP3 or FLAC, or an image is not a JPEG. File endpoints only. **`500 Internal Server Error`** - `internal_error`: the server failed while serving the request. Retry it; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is too busy to serve the request now. Retry it after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `config_invalid`, `audio_decode_failed`, `image_decode_failed`, `invalid_request`, `forbidden`, `not_found`, `method_not_allowed`, `audio_too_long`, `image_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — What went wrong, for a person. Its wording may change; switch on `code`.
- `request_id` (string, required) — Identifies the request in Hume's records. Quote it when contacting support.

## Types

### RunSummary

A run, as the list returns it.

- `run_id` (string, required) — The run's ID: the `session_id` of a realtime session, or the `run_id` of a file response.
- `user_id` (string, required) — The ID of the Hume user who made the run.
- `status` (enum, required) — Where a run is in its life: `live` while it is in progress, `ended` once it completed, and `errored` if it ended because of a failure or because the connection was lost. A live run the server has not heard from in five minutes is also reported `errored`, and reads `live` again if the server hears from it.
  - Allowed values: `live`, `ended`, `errored`
- `endpoint` (enum, required) — What the run measured.
  - Allowed values: `audio`, `video`
- `mode` (enum, required) — How the media reached the API.
  - Allowed values: `realtime`, `file`
- `started_at` (datetime, required) — When the run started.
- `ended_at` (datetime, required, nullable) — When the run ended. Null while it is in progress. For a run reported `errored` because the server stopped hearing from it, the last time the server heard from it.
- `bytes_received` (integer, required, nullable) — Bytes of media the server took in. A realtime video frame counts once it passes the send-rate check, even if it is then rejected as invalid. Null until the run ends, and for a run whose end was never recorded.
- `bytes_recorded` (integer, required, nullable) — How far the server got in storing the run's media, in bytes. Media that could not be stored is included, so this can exceed what was kept. Null when the run's media was not being stored, or when the server has not reported how much it stored, as early in a live run.
- `metered_seconds` (double, required) — Billable seconds for the run. For audio, this is the duration of the audio the server took in. For video, each frame or image the server took in counts as one third of a second, regardless of frame rate, including a realtime frame rejected as invalid after it passed the send-rate check. A run that took in any media is billed at least 10 seconds, applied when the run ends. Updated while a realtime run is in progress. A file request that fails is not billed, and a run recorded for it reports 0.

## Examples

**Response**

```json
{
  "runs": [
    {
      "run_id": "01926f3e-397d-7ceb-9f52-a864c0102a44",
      "user_id": "8d3f4a1e-6b2c-4f7d-9e0a-1b2c3d4e5f60",
      "status": "ended",
      "endpoint": "video",
      "mode": "file",
      "started_at": "2024-10-09T03:06:41.917Z",
      "ended_at": "2024-10-09T03:06:42.588Z",
      "bytes_received": 418302,
      "bytes_recorded": 418302,
      "metered_seconds": 10
    },
    {
      "run_id": "01926f3c-d33c-7c9f-9c91-4502d80834d5",
      "user_id": "8d3f4a1e-6b2c-4f7d-9e0a-1b2c3d4e5f60",
      "status": "ended",
      "endpoint": "audio",
      "mode": "file",
      "started_at": "2024-10-09T03:05:10.204Z",
      "ended_at": "2024-10-09T03:05:11.463Z",
      "bytes_received": 160000,
      "bytes_recorded": 160000,
      "metered_seconds": 10
    },
    {
      "run_id": "01926f3b-c943-7862-bce6-89e3ec968bf2",
      "user_id": "8d3f4a1e-6b2c-4f7d-9e0a-1b2c3d4e5f60",
      "status": "ended",
      "endpoint": "video",
      "mode": "realtime",
      "started_at": "2024-10-09T03:04:02.115Z",
      "ended_at": "2024-10-09T03:04:05.873Z",
      "bytes_received": 1811673,
      "bytes_recorded": 627453,
      "metered_seconds": 10
    },
    {
      "run_id": "01926f3a-5b1c-7d2e-8f40-3a9b7c1d2e5f",
      "user_id": "8d3f4a1e-6b2c-4f7d-9e0a-1b2c3d4e5f60",
      "status": "ended",
      "endpoint": "audio",
      "mode": "realtime",
      "started_at": "2024-10-09T03:02:28.380Z",
      "ended_at": "2024-10-09T03:02:55.104Z",
      "bytes_received": 832000,
      "bytes_recorded": 832000,
      "metered_seconds": 26
    }
  ],
  "next_cursor": "2024-10-09T03:02:28.380000Z|01926f3a-5b1c-7d2e-8f40-3a9b7c1d2e5f"
}
```