Extra Metadata

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 \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?extra=KEY:VALUE'

🚧

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

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:

{
  "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

🚧

If you 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 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