Tagging

Tagging allows you to label your requests for the purpose of identification during usage reporting.

tag string.

Deepgram’s Tagging feature allows you to label your API requests for the purpose of identification during usage reporting. You can also apply tags to API Keys; if you do, any tags applied to the API Key running the API request will also be applied to the request itself.

Tags are limited to 128 characters per tag.

Enable Feature

To enable Tagging, when you call Deepgram’s API, add a tag parameter in the query string and set it to the tag you would like to recognize:

tag=VALUE

To transcribe audio from a file on your computer, run the following cURL command in a terminal or your favorite API client. Please be aware that once you have set a tag, you cannot modify it.

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

🚧

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Filter Requests by Tag

Once applied, you can identify tags associated with API requests returned by the Get All Requests, Get Request, and Get Fields endpoints.

You can also directly query requests by tag at the Summarize Usage endpoint.

curl \
  --request GET \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'content-type: application/json'
  --url 'https://api.deepgram.com/v1/projects/PROJECT_ID/usage?tag=VALUE'

🚧

Replace the placeholder PROJECT_ID with your Deepgram Console Project ID, VALUE with your tag, and YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Special Considerations

White Space or Special Characters

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

tag=marketing%20team or tag=marketing+team

Apply Multiple Instances

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

tag=marketing&tag=legal

Comparison to Extra Metadata

Extra Metadata is a similar feature to Tagging. Where Tagging is primarily intended for tracking and filtering usage, Extra Metadata is useful for passing data to downstream processing steps.

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

TaggingExtra Metadata
Primarily for passing data to downstream processing steps:x::white-check-mark:
Primarily for tracking usage:white-check-mark::x:
Configurable per request:white-check-mark::white-check-mark:
Configurable per API key:white-check-mark::x:
Character limit per value128 chars2048 chars
Can be used to filter usage:white-check-mark::x:
Can specify a key in a key-value pair:x::white-check-mark:
Can specify a value in a key-value pair:white-check-mark::white-check-mark:

Use Cases

Some examples of use cases for Tagging include:

  • Customers who have multiple, related business projects and need to track separate usage.
  • Customers who have projects managed by different business teams or under different cost centers.
  • Customers who operate a business-to-business (B2B) model that focuses on selling products and services to other companies. Rather than creating separate projects to track usage data, you can create a separate API Key for each company and tag it with the their information. Any requests run using the API Key will also be tagged with that company's information.

What’s Next