> 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 GET https://api.cloud.hume.ai/v1/expression/run/{run_id} The run's status, when it started and ended, what it received and stored, and the configuration it ran under. Reference: https://dev.hume.ai/expression-measurement/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 `session_id` of a realtime session or the `run_id` of a file response. ## Response ### 200 The run. - `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. - `close_code` (integer, required, nullable) — The WebSocket close code the session ended with, or 1011 if the connection was lost without a close frame. Only realtime runs that have ended have one, and not all of those: it is absent when the client's close frame carried no code, or when the server stopped before recording how the session closed. - `close_reason` (string, required, nullable) — Why the session closed: `client_request`, `server_shutdown`, `idle_timeout` or `error` when the server closed it, `error` when the connection was lost without a close frame, and otherwise the reason text from the client's close frame. Only realtime runs that have ended have one, and not all of those: it is absent when the client's close frame carried no code, or when the server stopped before recording how the session closed. - `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. - `config` (RunConfig, required) — The configuration the run ran under, including defaults for any settings the request did not set. ## Errors ### 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 ### RunConfig The configuration the run ran under, including defaults for any settings the request did not set. - Audio run configuration: AudioRunConfig - Video run configuration: VideoRunConfig ### AudioRunConfig The configuration an audio run ran under. - `schema` ("v4", required) — Identifies the layout of this configuration. Check it if you store configurations, so one in a later layout is recognized rather than misread. - `audio` (AudioConfig, required) — The audio format. - `measurement_timer_ms` (integer, required) — How often the run measured within an utterance, in milliseconds of speech. ### VideoRunConfig The configuration a video run ran under. - `schema` ("v4", required) — Identifies the layout of this configuration. Check it if you store configurations, so one in a later layout is recognized rather than misread. - `image` (ImageConfig, required) — The image format. - `face` (FaceConfig, required) — The face detection settings. ### AudioConfig The audio format. - `type` ("audio/pcm", required) - `encoding` ("s16le", required) — The sample encoding. `s16le` is signed 16-bit little-endian PCM. - `sample_rate` (integer, required) — The sample rate in Hz. - `channels` (integer, required) ### ImageConfig The image format. - `type` ("image/jpeg", required) ### FaceConfig The face detection settings. - `threshold` (double, required) — Minimum detection confidence for a face to be measured. Lower values include more faces at the risk of false detections. This scale is specific to this API; thresholds tuned for other face detection APIs do not carry over. Reported rounded to four decimal places. - `min_size` (integer, required) — Minimum face size to measure, as the shorter side of the face's bounding box in pixels of the submitted image. ## Examples **Response** ```json { "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", "close_code": 1000, "close_reason": "client_request", "bytes_received": 832000, "bytes_recorded": 832000, "metered_seconds": 26, "config": { "audio": { "channels": 1, "encoding": "s16le", "sample_rate": 16000, "type": "audio/pcm" }, "measurement_timer_ms": 3000, "schema": "v4" } } ```