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.Authorizations
Authentication with Authorization header and DeepL-Auth-Key authentication scheme. Example: DeepL-Auth-Key <api-key>
Query Parameters
Start date for the usage report (ISO 8601 date format).
End date for the usage report (ISO 8601 date format).
Optional parameter to control aggregation of usage statistics. Possible values:
period- Aggregate usage over the entire date range (default)day- Group usage by individual day
Available options:
period, day Page number for pagination. Use the integer value returned in next_page from
a previous response to retrieve the next page of results.
Response
The custom tag usage statistics for the specified date range.
The response for admin custom tag usage statistics.
Contains the detailed custom tag usage statistics for the specified date range.
Show child attributes
Show child attributes