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

:::callout{intent="warning"}
Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](/guides/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`

:::callout{intent="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](/guides/results-processing-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                   | ✅              | ✅         |
|                                                           |                |           |

***

## Related pages

- [Amazon SageMaker](./amazon-sagemaker-index.md)
- [Aura](./aura-index.md)
- [Changelog](../changelog.md)
- [Custom Vocabulary](./custom-vocabulary-index.md)
- [Deepgram's Docs](../index.md)
- [Deployment](./deployment-index.md)
- [Docker/Podman](./docker-podman-index.md)
- [Features](./features-index.md)
- [Flux TTS](./flux-tts-index.md)
- [Formatting](./formatting-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.