Translate
Customize
Languages
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
}
},
{
"custom_tag": "example-custom-tag-2",
"breakdown": {
"total_characters": 475,
"text_translation_characters": 475,
"text_improvement_characters": 0
}
}
]
}
}Get custom tag usage analytics
Retrieve usage statistics broken down by custom tags within a specified date range.
Optionally aggregate results by day or over the entire period.
Results are paginated; use the page parameter with the next_page value from
a previous response to retrieve subsequent pages.
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
}
},
{
"custom_tag": "example-custom-tag-2",
"breakdown": {
"total_characters": 475,
"text_translation_characters": 475,
"text_improvement_characters": 0
}
}
]
}
}Documentation Index
Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
Use this file to discover all available pages before exploring further.
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 identifierbreakdown: character counts split by service type
Usage breakdown
| Field | Description |
|---|---|
total_characters | Combined character usage across all services |
text_translation_characters | Characters used for text translation |
text_improvement_characters | Characters used for text improvement (rephrasing) |
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
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