> ## 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.
# 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.
## 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`.
## OpenAPI
````yaml get /v2/admin/analytics/custom-tags
openapi: 3.0.3
info:
title: DeepL API Documentation
description: >-
The DeepL API provides programmatic access to DeepL’s language AI
technology.
Note: this OpenAPI spec is embedded into our API documentation and has
shortened descriptions.
termsOfService: https://www.deepl.com/pro-license
contact:
name: DeepL - Contact us
url: https://www.deepl.com/contact-us
version: 3.10.0
servers:
- url: https://api.deepl.com
description: DeepL API Pro
- url: https://api-free.deepl.com
description: DeepL API Free
security: []
tags:
- name: beta
description: >-
Experimental features that are under testing and not yet intended for
production use.
- name: TranslateText
description: >-
The text-translation API currently consists of a single endpoint,
`translate`, which is described below.
- name: TranslateDocuments
description: >-
The document translation API allows you to translate whole documents and
supports the following file types and extensions:
* `docx` - Microsoft Word Document
* `pptx` - Microsoft PowerPoint Document
* `xlsx` - Microsoft Excel Document
* `pdf` - Portable Document Format
* `htm / html` - HTML Document
* `txt` - Plain Text Document
* `xlf / xliff` - XLIFF Document, version 2.1
* `srt` - SRT Document
* `jpeg` / `jpg` / `png` - Image (currently in beta)
- name: RephraseText
description: >-
The `rephrase` endpoint is used to make corrections and adjustments to
texts based on style or tone.
- name: CorrectText
description: >-
The `correct` endpoint fixes spelling and grammar errors without broader
rephrasing. Use it when you want
a minimal-change correction pass rather than the broader rewriting
performed by `rephrase`.
- name: ManageMultilingualGlossaries
description: >-
The *glossary* functions allow you to create, inspect, edit and delete
glossaries.
Glossaries created with the glossary function can be used in translate
requests by specifying the
`glossary_id` parameter. A glossary contains (several) dictionaries.
A dictionary is a mapping of source phrases to target phrases for a single
language pair.
If you encounter issues, please let us know at support@DeepL.com.
Currently you can create glossaries with any of the languages DeepL
supports (with the exception of Thai).
The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each
source/target text,
as well as the name of the glossary, is limited to 1024 UTF-8 bytes.
A total of 1000 glossaries are allowed per account.
When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's
not necessary to specify a variant
(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
Dictionaries with target language `EN` can be used in translations with
either English variant.
Similarly `PT`, and `ZH` dictionaries can be used in translations with
their corresponding variants.
(When you provide the ID of a glossary to a translation, the appropriate
dictionary is automatically applied. Currently glossaries can not yet be
used with source language detection.)
Glossaries created via the DeepL API are now unified with glossaries
created via the DeepL website and DeepL apps.
Please only use the v3 glossary API in conjunction with multilingual or
edited glossaries from the website.
- name: ManageGlossaries
description: >-
Please note that this is the spec for the (old) v2 glossary endpoint.
We recommend users switch to the newer v3 glossary endpoints, which
support editability and multilinguality.
The *glossary* functions allow you to create, inspect, and delete
glossaries.
Glossaries created with the glossary function can be used in translate
requests by specifying the
`glossary_id` parameter.
If you encounter issues, please let us know at support@DeepL.com.
Currently you can create glossaries with any of the languages DeepL
supports (with the exception of Thai).
- name: MetaInformation
description: Information about API usage and value ranges
- name: TranslationMemories
description: >-
The translation memory endpoints allow you to interact with your account's
translation memories, used to store
and reuse previously created translations. Translation memories can be
used in text translation requests by
specifying the `translation_memory_id` parameter to denote a specific
translation memory and the
`translation_memory_threshold` which defines the minimum matching
percentage required for a translation memory
segment to be applied (recommended to be 75% or higher).
- name: VoiceAPI
description: >-
The Voice API provides real-time voice transcription and translation
services.
Use a two-step flow: first request a streaming URL via REST, then
establish a WebSocket connection for streaming audio and receiving
transcriptions.
- name: VoiceTranslateJob
description: >-
**Alpha.** Async voice translation jobs. This API may change without
notice.
- name: AdminApi
description: >-
Endpoints for organization administrators to manage API keys and retrieve
usage analytics.
- name: QualityEvaluation
description: >-
**Closed alpha.** Evaluate translation quality. Submit source/target
segment pairs and retrieve per-segment quality issues categorized by error
type and severity, with character spans pointing to where each issue
occurs.
externalDocs:
description: DeepL Pro - Plans and pricing
url: https://www.deepl.com/pro#developer
paths:
/v2/admin/analytics/custom-tags:
get:
tags:
- AdminApi
summary: Get custom tag usage statistics as an admin
description: >-
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.
operationId: adminGetCustomTagAnalytics
parameters:
- name: start_date
in: query
required: true
description: Start date for the usage report (ISO 8601 date format).
schema:
type: string
format: date
example: '2026-05-17'
- name: end_date
in: query
required: true
description: End date for the usage report (ISO 8601 date format).
schema:
type: string
format: date
example: '2026-05-18'
- name: aggregate_by
in: query
required: false
description: >-
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
schema:
type: string
enum:
- period
- day
default: period
example: day
- name: page
in: query
required: false
description: >-
Page number for pagination. Use the integer value returned in
`next_page` from
a previous response to retrieve the next page of results.
schema:
type: integer
example: 2
responses:
'200':
description: The custom tag usage statistics for the specified date range.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/CustomTagUsageReport'
examples:
aggregateByPeriod:
summary: Usage report aggregated over the full period
value:
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
aggregateByDay:
summary: Usage report aggregated by day
value:
custom_tag_usage_report:
aggregate_by: day
start_date: '2026-05-03T00:00:00'
end_date: '2026-05-15T00:00:00'
next_page: null
usage:
- custom_tag: example-custom-tag
usage_date: '2026-05-04T00:00:00Z'
breakdown:
total_characters: 380
text_translation_characters: 380
text_improvement_characters: 0
- custom_tag: example-custom-tag
usage_date: '2026-05-11T00:00:00Z'
breakdown:
total_characters: 595
text_translation_characters: 595
text_improvement_characters: 0
'400':
description: Bad request. Please check error message and your parameters.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message describing the issue.
examples:
dateRangeExceeded:
summary: Date range exceeds maximum allowed
value:
message: 'Bad request. Reason: Date range cannot exceed 366 days'
invalidAggregateBy:
summary: Invalid aggregate_by parameter value
value:
message: >-
Value for 'aggregate_by' not supported. Allowed: '',
'period', 'day'.
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- auth_header: []
components:
headers:
X-Trace-ID:
description: >-
A unique identifier for the request that can be included in bug reports
to DeepL support.
schema:
type: string
example: 501c3d93cc0c4f11ae2f60a226c2f0f0
schemas:
CustomTagUsageReport:
type: object
description: The response for admin custom tag usage statistics.
properties:
custom_tag_usage_report:
$ref: '#/components/schemas/CustomTagUsageReportData'
CustomTagUsageReportData:
type: object
description: >-
Contains the detailed custom tag usage statistics for the specified date
range.
properties:
aggregate_by:
type: string
description: The aggregation method used.
enum:
- period
- day
example: period
start_date:
type: string
format: date-time
description: Start date of the usage report period.
example: '2026-05-03T00:00:00'
end_date:
type: string
format: date-time
description: End date of the usage report period.
example: '2026-05-05T00:00:00'
next_page:
type: integer
nullable: true
description: >-
Cursor for the next page of results. Null if there are no further
pages.
example: 2
usage:
type: array
description: List of custom tag usage entries.
items:
$ref: '#/components/schemas/CustomTagUsageItem'
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: A human-readable description of the error.
code:
type: string
description: >-
A machine-readable identifier for the error, when available. Clients
should match on this value rather than on `message` when branching
on error types.
example: invalid_content_type
CustomTagUsageItem:
type: object
description: Usage statistics for a specific custom tag.
properties:
custom_tag:
type: string
description: The custom tag identifier.
example: example-custom-tag
usage_date:
type: string
format: date-time
description: >-
The day the usage was recorded. Only returned when `aggregate_by` is
`day`.
example: '2026-05-04T00:00:00Z'
breakdown:
$ref: '#/components/schemas/CustomTagBreakdown'
CustomTagBreakdown:
type: object
description: Breakdown of character usage by category for a custom tag.
properties:
total_characters:
type: integer
description: Total number of characters used.
example: 380
text_translation_characters:
type: integer
description: Number of characters used for text translation.
example: 380
text_improvement_characters:
type: integer
description: Number of characters used for text improvement.
example: 0
responses:
Forbidden:
description: >-
Authorization failed. Please supply a valid `DeepL-Auth-Key` via the
`Authorization` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: The requested resource could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal error.
securitySchemes:
auth_header:
type: apiKey
description: >
Authentication with `Authorization` header and `DeepL-Auth-Key`
authentication scheme. Example: `DeepL-Auth-Key `
name: Authorization
in: header
x-default: 'DeepL-Auth-Key '
````