> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/expression-measurement/reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# API Reference


## API Docs

- Expression Measurement API > Audio [Stream audio](https://dev.hume.ai/expression-measurement/reference/audio/stream-audio.md)
- Expression Measurement API > Audio [Upload audio](https://dev.hume.ai/expression-measurement/reference/audio/measure.md)
- Expression Measurement API > Video [Stream images](https://dev.hume.ai/expression-measurement/reference/video/stream-images.md)
- Expression Measurement API > Video [Upload images](https://dev.hume.ai/expression-measurement/reference/video/measure.md)
- Expression Measurement API > Runs [List runs](https://dev.hume.ai/expression-measurement/reference/runs/list.md)
- Expression Measurement API > Runs [Get run](https://dev.hume.ai/expression-measurement/reference/runs/get.md)
- Expression Measurement API > Runs [Get run events](https://dev.hume.ai/expression-measurement/reference/runs/list-events.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://dev.hume.ai/openapi.json)
- [OpenAPI YAML](https://dev.hume.ai/openapi.yaml)


## AsyncAPI Specification

The raw AsyncAPI 2.6.0 specification for the WebSocket channels is available at:
- [AsyncAPI JSON](https://dev.hume.ai/asyncapi.json)
- [AsyncAPI YAML](https://dev.hume.ai/asyncapi.yaml)


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/expression-measurement/reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# Expression Measurement API

> **Info**
>
> The API is currently in limited release; [contact our team](https://www.hume.ai/sales-form) to request access.

**This reference lists every endpoint of the Expression Measurement API, with the parameters, fields, and messages each one accepts and returns.** To learn how the endpoints fit together, start with the [overview](/expression-measurement/docs/overview).

## Base URLs

<table>
  <thead>
    <tr>
      <th width="28%">
        Protocol
      </th>

      <th>
        Base URL
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        HTTP
      </td>

      <td>
        `https://api.cloud.hume.ai`
      </td>
    </tr>

    <tr>
      <td>
        WebSocket
      </td>

      <td>
        `wss://api.cloud.hume.ai`
      </td>
    </tr>
  </tbody>
</table>

## Authentication

Every request carries a credential header: an API key in `X-Hume-Api-Key`, or an access token in `Authorization: Bearer <token>`. On a realtime endpoint, the header goes on the handshake request that opens the WebSocket. See [Authentication](/expression-measurement/docs/authentication).

## Endpoints

<table>
  <thead>
    <tr>
      <th width="48%">
        Endpoint
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        [`WSS /v1/expression/audio/realtime`](/expression-measurement/reference/audio/stream-audio)
      </td>

      <td>
        Stream audio and receive measurements for each utterance.
      </td>
    </tr>

    <tr>
      <td>
        [`POST /v1/expression/audio/file`](/expression-measurement/reference/audio/measure)
      </td>

      <td>
        Upload an audio file and receive measurements for every utterance.
      </td>
    </tr>

    <tr>
      <td>
        [`WSS /v1/expression/video/realtime`](/expression-measurement/reference/video/stream-images)
      </td>

      <td>
        Stream video as JPEG frames and receive scores for the faces in each frame.
      </td>
    </tr>

    <tr>
      <td>
        [`POST /v1/expression/video/file`](/expression-measurement/reference/video/measure)
      </td>

      <td>
        Upload JPEG images and receive scores for the faces in each image.
      </td>
    </tr>

    <tr>
      <td>
        [`GET /v1/expression/run`](/expression-measurement/reference/runs/list)
      </td>

      <td>
        Paginated list of your organization's runs.
      </td>
    </tr>

    <tr>
      <td>
        [`GET /v1/expression/run/{run_id}`](/expression-measurement/reference/runs/get)
      </td>

      <td>
        One run: its status and configuration.
      </td>
    </tr>

    <tr>
      <td>
        [`GET /v1/expression/run/{run_id}/events`](/expression-measurement/reference/runs/list-events)
      </td>

      <td>
        The problems the run reported, in order.
      </td>
    </tr>
  </tbody>
</table>

## Errors

The upload and run endpoints return an HTTP error response, and realtime sessions send an `error` message. Both carry a `code` to branch on and a `message` for people to read. See [Errors](/expression-measurement/docs/errors).

## SDKs

<table>
  <thead>
    <tr>
      <th width="28%">
        Language
      </th>

      <th>
        Package
      </th>

      <th>
        Guide
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Python
      </td>

      <td>
        [`hume-expression-measurement`](https://pypi.org/project/hume-expression-measurement/)
      </td>

      <td>
        [Python quickstart](/expression-measurement/docs/quickstart/python)
      </td>
    </tr>

    <tr>
      <td>
        Node.js
      </td>

      <td>
        [`@humeai/expression-measurement-node`](https://www.npmjs.com/package/@humeai/expression-measurement-node)
      </td>

      <td>
        [Node.js quickstart](/expression-measurement/docs/quickstart/nodejs)
      </td>
    </tr>
  </tbody>
</table>