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.

GET /v2/admin/analytics/custom-tags

Get custom tag usage statistics as an admin

cURL

curl --request GET \
  --url https://api.deepl.com/v2/admin/analytics/custom-tags \
  --header 'Authorization: <api-key>'

200

aggregateByPeriod

{ "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 } } ] } }

Date range

Specify the reporting window using the required start_date and end_date parameters in ISO 8601 date format (e.g., 2026-05-01). The maximum date range is 366 days.

Aggregation

The optional aggregate_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

Use 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 a custom_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

Each entry in usage includes:

• custom_tag: the tag identifier
• usage_date: the day the usage was recorded (ISO 8601 datetime). Only returned when aggregate_by is day
• breakdown: 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)

Custom tag data is supported only for text translation. Support for other request types will be added in a future update.

Pagination

Results are paginated. If the response includes a non-null next_page value, pass it as the page parameter in your next request to retrieve the following page. Continue until next_page is null.

Authorizations

Authorization · string · header · default: DeepL-Auth-Key · required

Authentication with Authorization header and DeepL-Auth-Key authentication scheme. Example: DeepL-Auth-Key <api-key>

Query Parameters

start_date · string<date> · required

Start date for the usage report (ISO 8601 date format).

end_date · string<date> · required

End date for the usage report (ISO 8601 date format).

aggregate_by · enum<string> · default: period

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 · integer

Page number for pagination. Use the integer value returned in next_page from a previous response to retrieve the next page of results.

Response

200

application/json

The custom tag usage statistics for the specified date range.

The response for admin custom tag usage statistics.

custom_tag_usage_report · object

Contains the detailed custom tag usage statistics for the specified date range.

Show child attributes