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: