> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.deepgram.com/docs/extra-metadata/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.deepgram.com/_mcp/server.

# Extra Metadata

`extra` *string*

Pre-recorded  Streaming:Nova Streaming: Flux  All available languages

Deepgram’s Extra Metadata feature allows you to attach arbitrary key-value pairs to your API requests that are attached to the API response for usage in downstream processing.

Extra metadata is limited to 2048 characters per key-value pair.

## Enable Feature

To enable Extra Metadata, when you call Deepgram’s API, add an `extra` parameter in the query string and pass a key-value pair you would like to include in the response.

`extra=KEY:VALUE`

To transcribe audio from a file on your computer, run the following cURL command in a terminal or your favorite API client.

**`cURL`**

```bash cURL
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?extra=KEY:VALUE'
```

> **Warning**
>
> Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](/guides/fundamentals/make-your-first-api-request).

## Response

If you included `extra=myKey:someValue` in your request, the key-value pair would be passed through to the response in the following format:

**`JSON`**

```json JSON
{
  "metadata": {
    "extra": {
      "myKey": "someValue"
    }
    ...
  }
  ...
}
```

## Special Considerations

### White Space or Special Characters

If your extra metadata includes spaces or special characters, be sure to URL encode it:

`extra=dataflow:marketing%20team` or `extra=dataflow:marketing+team`

### Apply Multiple Instances

To apply multiple extra key-value pairs, submit the query parameter multiple times in your API request:

`extra=team:marketing&extra=purpose:legal`

> **Warning**
>
> If your request contains multiple instances of `extra` with the same key, the corresponding values will *not* be merged. Instead, the last value will overwrite any previous values.
>
> For example, `extra=team:marketing&extra=team:gtm` will return `"extra": { "team": "gtm" }` in the response.

## Comparison to Tagging

[Tagging](/docs/stt-tagging) is a similar feature to Extra Metadata. Where Extra Metadata is primarily intended for passing data to downstream processing steps, Tagging is useful for tracking and filtering usage.

Below is a comparison table summarizing the main differences between the two features:

|                                                           | Extra Metadata | Tagging   |
| --------------------------------------------------------- | -------------- | --------- |
| Primarily for passing data to downstream processing steps | ✅              | ❌         |
| Primarily for tracking usage                              | ❌              | ✅         |
| Configurable per request                                  | ✅              | ✅         |
| Configurable per API key                                  | ❌              | ✅         |
| Character limit per value                                 | 2048 chars     | 128 chars |
| Can be used to filter usage                               | ❌              | ✅         |
| Can specify a key in a key-value pair                     | ✅              | ❌         |
| Can specify a value in a key-value pair                   | ✅              | ✅         |
|                                                           |                |           |

---

> Extra Metadata allows you to label your requests for the purpose of identification in downstream processing.