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

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