Extra Metadata

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

extra string.

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

🚧

Duplicate Keys

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 MetadataTagging
Primarily for passing data to downstream processing steps:white-check-mark::x:
Primarily for tracking usage:x::white-check-mark:
Configurable per request:white-check-mark::white-check-mark:
Configurable per API key:x::white-check-mark:
Character limit per value2048 chars128 chars
Can be used to filter usage:x::white-check-mark:
Can specify a key in a key-value pair:white-check-mark::x:
Can specify a value in a key-value pair:white-check-mark::white-check-mark:

Use Cases

Some examples of use cases for Extra Metadata include:

  • Customers who have downstream processing steps after Deepgram's API response that need to be aware of specific data values from upstream processing steps.
  • Customers who have an internal ID associated with data that is being sent to Deepgram, and need to persist this ID throughout their data pipeline. This may be especially relevant when using message brokers, such as Kafka or RabbitMQ.

What’s Next