Get custom tag usage statistics as an admin
curl --request GET \
--url https://api.deepl.com/v2/admin/analytics/custom-tags \
--header 'Authorization: <api-key>'{
"custom_tag_usage_report": {
"aggregate_by": "period",
"start_date": "2026-05-03T00:00:00",
"end_date": "2026-05-05T00:00:00",
"next_page": null,
"usage": [
{
"custom_tag": "example-custom-tag",
"breakdown": {
"total_characters": 380,
"text_translation_characters": 380,
"text_improvement_characters": 0,
"speech_to_text_minutes": 12.5,
"speech_to_speech_minutes": 4.2
}
},
{
"custom_tag": "example-custom-tag-2",
"breakdown": {
"total_characters": 475,
"text_translation_characters": 475,
"text_improvement_characters": 0,
"speech_to_text_minutes": 0,
"speech_to_speech_minutes": 0
}
}
]
}
}Organization Usage Analytics
Get custom tag usage analytics
Retrieve DeepL API usage broken down by custom tag for a date range, optionally aggregated by day, with paginated results.
GET
/
v2
/
admin
/
analytics
/
custom-tags
Get custom tag usage statistics as an admin
curl --request GET \
--url https://api.deepl.com/v2/admin/analytics/custom-tags \
--header 'Authorization: <api-key>'{
"custom_tag_usage_report": {
"aggregate_by": "period",
"start_date": "2026-05-03T00:00:00",
"end_date": "2026-05-05T00:00:00",
"next_page": null,
"usage": [
{
"custom_tag": "example-custom-tag",
"breakdown": {
"total_characters": 380,
"text_translation_characters": 380,
"text_improvement_characters": 0,
"speech_to_text_minutes": 12.5,
"speech_to_speech_minutes": 4.2
}
},
{
"custom_tag": "example-custom-tag-2",
"breakdown": {
"total_characters": 475,
"text_translation_characters": 475,
"text_improvement_characters": 0,
"speech_to_text_minutes": 0,
"speech_to_speech_minutes": 0
}
}
]
}
}Date range
Specify the reporting window using the requiredstart_date and end_date parameters in ISO 8601 date format (e.g., 2026-05-01). The maximum date range is 366 days.
Aggregation
The optionalaggregate_by parameter controls how usage is grouped:
| Value | Description |
|---|---|
period (default) | Returns total usage per custom tag over the entire date range |
day | Returns usage per custom tag broken down by individual day |
period when you need a summary for billing or reporting. Use day when you need to analyze usage trends over time.
Response structure
The response contains acustom_tag_usage_report object with the following fields:
| Field | Description |
|---|---|
aggregate_by | The aggregation method used (period or day) |
start_date | Start of the reporting period (ISO 8601 datetime) |
end_date | End of the reporting period (ISO 8601 datetime) |
next_page | Integer cursor for the next page of results. null if there are no further pages |
usage | Array of usage entries, one per custom tag |
usage includes:
custom_tag: the tag identifierusage_date: the day the usage was recorded (ISO 8601 datetime). Only returned whenaggregate_byisdaybreakdown: usage split by service type
Usage breakdown
| Field | Description |
|---|---|
total_characters | Combined character usage across character-based services |
text_translation_characters | Characters used for text translation |
text_improvement_characters | Characters used for text improvement (rephrasing) |
speech_to_text_minutes | Minutes of speech-to-text usage. Fractional values are returned, for example 12.5 |
speech_to_speech_minutes | Minutes of speech-to-speech usage. Fractional values are returned, for example 4.2 |
total_characters, which covers character-based services only.
Custom tag data is recorded only for text translation and Voice API requests. Support for other request types will be added in a future update.
Pagination
Results are paginated. If the response includes a non-nullnext_page value, pass it as the page parameter in your next request to retrieve the following page. Continue until next_page is null.