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

# Get run events

GET https://api.cloud.hume.ai/v1/expression/run/{run_id}/events

The problems the run reported, in order: frames it rejected and failures it hit. A run that went well has none. Only realtime sessions record them.

Reference: https://dev.hume.ai/expression-measurement/reference/runs/list-events

## Authentication

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

## Request

### Path parameters

- `run_id` (string, required) — The run's ID: the `session_id` of a realtime session or the `run_id` of a file response.

### Query parameters

- `page_size` (integer, optional, default: 50) — How many entries to return.
- `cursor` (string, optional) — The `next_cursor` of the previous page. Pass it back unchanged.

## Response

### 200

One page of the run's event log.

- `events` (list of RunEvent, required) — The entries, in `seq` order.
- `at_cap` (boolean, required) — Whether some kind of event used up its per-run logging limit. Any later events of that kind were not logged, though there may have been none. When `gaps` is true, a false value cannot be relied on. `capped_kinds` names the kinds.
- `capped_kinds` (list of enum, required) — The kinds that used up their limit. Empty when none did.
  - Allowed values: `invalid_audio_frame`, `invalid_image_frame`, `rate_limited`, `inference_failed`, `message_too_large`, `video_recording_abandoned`
- `gaps` (boolean, required) — Whether entries are missing from the log: events that were numbered and never stored.
- `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.

### 404 Not Found Error

No run with this ID exists in your organization.

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

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

### RunEvent

One entry in a run's event log.

- `seq` (integer, required) — The entry's position in the log.
- `at` (datetime, required) — When the event was recorded.
- `kind` (enum, required) — What a run's event log records. Every kind is something the run refused or that went wrong, so a run that went well has no events. - `invalid_audio_frame`: an audio frame was rejected. Audio only. - `invalid_image_frame`: an image frame was rejected, or face detection failed on a frame and the session reported `internal_error`. Video only. - `rate_limited`: media arrived faster than the send rate and a frame was rejected. - `inference_failed`: a frame was skipped because its measurement failed, which the session reported as `internal_error`. Video only. - `message_too_large`: a message exceeded the size limit and the session ended. - `video_recording_abandoned`: the server stopped storing the run's frames or images; results were still delivered. Video only, and only on runs recorded before the server stopped emitting it. Only realtime sessions record events. A file request that hits any other problem fails as a whole and reports it in the response instead.
  - Allowed values: `invalid_audio_frame`, `invalid_image_frame`, `rate_limited`, `inference_failed`, `message_too_large`, `video_recording_abandoned`
- `detail` (RunEventDetail, optional) — Details, depending on `kind`: the reason a frame was rejected (`detail`), the size limit a message exceeded (`limit_bytes`), whether a measurement failure was temporary and how many failed in a row (`retryable`, `consecutive`), or why recording stopped (`reason`). Absent for `rate_limited`.

### RunEventDetail

Details, depending on `kind`: the reason a frame was rejected (`detail`), the size limit a message exceeded (`limit_bytes`), whether a measurement failure was temporary and how many failed in a row (`retryable`, `consecutive`), or why recording stopped (`reason`). Absent for `rate_limited`.

## Examples

**Response**

```json
{
  "events": [
    {
      "seq": 1,
      "at": "2024-10-09T02:47:15.911Z",
      "kind": "invalid_audio_frame",
      "detail": {
        "detail": "binary audio frame must contain complete 16-bit PCM samples"
      }
    },
    {
      "seq": 2,
      "at": "2024-10-09T02:47:16.240Z",
      "kind": "rate_limited"
    }
  ],
  "at_cap": true,
  "capped_kinds": [
    "rate_limited"
  ],
  "gaps": false,
  "next_cursor": "2"
}
```