How to Use Custom Reporting Tags

• When to use custom reporting tags
• How to attach a tag to a text translation or Voice API request via the X-DeepL-Reporting-Tag header
• Tag naming guidance and current limitations

​

What custom reporting tags are for

• Multi-tenant applications: attribute translation volume to the end customer making each request
• Internal cost allocation: split usage across teams or business units that share a single API key

​

How to tag a translate request

curl --request POST 'https://api.deepl.com/v2/translate' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'X-DeepL-Reporting-Tag: team-billing' \
--header 'Content-Type: application/json' \
--data '{
  "text": ["Welcome to your dashboard."],
  "target_lang": "DE"
}'

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Willkommen in Ihrem Dashboard."
    }
  ]
}

​

How to tag a Voice API session

curl --request POST 'https://api.deepl.com/v3/voice/realtime' \
--header 'Authorization: DeepL-Auth-Key [your key]' \
--header 'X-DeepL-Reporting-Tag: team-billing' \
--header 'Content-Type: application/json' \
--data '{
  "source_media_content_type": "audio/ogg;codecs=opus",
  "source_language_mode": "auto",
  "target_languages": ["de"]
}'

{
  "streaming_url": "wss://api.deepl.com/v3/voice/realtime/connect",
  "token": "VGhpcyBpcyBhIGZha2UgdG9rZW4K",
  "session_id": "4f911080-cfe2-41d4-8269-0e6ec15a0354"
}

​

Tag naming guidance

• Tags are caller-defined strings. The API records the value you send after applying the normalization rules below.
• Before storage, the API trims leading and trailing whitespace and lowercases the value, so " Sample-Tag" is recorded as sample-tag and appears that way in analytics responses.
• After normalization, characters are matched exactly. team-billing and team_billing report as two separate tags.
• Pick a convention and stick to it. Examples: team-billing, customer-{id}, project-{id}.

​

Tags and API keys

​

Limitations

• Tag values are limited to 100 characters. Requests with longer values are rejected with a 400 response.
• Tag values must use ASCII characters only, with no internal whitespace and no control characters. Values like sample tag, sample-tág, or sample\ntag are rejected with a 400 response. Leading and trailing whitespace is trimmed before validation (see Tag naming guidance).
• Each request accepts one tag. Sending multiple values in the header is not supported.
• For the Voice API, a tag covers a whole session and can only be set on the session request. See How to tag a Voice API session.
• Untagged requests are not included in custom-tag analytics. They still count toward your overall usage, which you can retrieve through the Get usage analytics endpoint.

​

Next steps

• Use the client libraries: See Sending Custom Reporting Tags with Client Libraries for code snippets in Python, Node.js, Java, .NET, and PHP.
• Query your tagged usage: See the Get custom tag usage analytics reference for date ranges, aggregation options, and pagination, or download a custom tag-level CSV export from the account UI.
• Get the bigger picture: Read the usage data guide to understand how custom-tag reporting fits alongside the other usage data sources.
• Explore other optional translate parameters: Learn how to use the context parameter to improve translation accuracy for ambiguous content.