Get custom tag usage analytics - DeepL Documentation

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
        }
      },
      {
        "custom_tag": "example-custom-tag-2",
        "breakdown": {
          "total_characters": 475,
          "text_translation_characters": 475,
          "text_improvement_characters": 0
        }
      }
    ]
  }
}

GET

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

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

Get usage analytics

⌘I

​Date range

​Aggregation

​Response structure

​Usage breakdown

​Pagination

Authorizations

Query Parameters

Response

Date range

Aggregation

Response structure

Usage breakdown

Pagination