> ## 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. > ## Agent Instructions > Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints. > Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication). > Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key `. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart. > Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid. # Get language pair usage analytics > Learn how to retrieve DeepL API usage per source and target language pair for a date range, optionally grouped by API key and aggregated by day. ## Availability Language pair-level data is generally available on the API Enterprise plan. On the API Pro plan, it's available on request; contact your customer success manager to enable it. If your admin key belongs to an account without language pair-level data, the request succeeds and returns an empty `language_pair_usages` array. ## Date range Specify the reporting window using the required `start_date` and `end_date` parameters in ISO 8601 date format (e.g., `2026-10-01`). Both are interpreted in UTC. * `start_date` can't be after the current UTC day * `start_date` can't be more than 63 days before the current UTC day Requests that break either rule return a `400` error. Usage data is available up to and including the previous UTC calendar day, so that is the latest day `end_date` can include. ## Grouping and aggregation Two optional parameters control how usage is organized. | **Parameter** | **Value** | **Description** | | :- | :- | :- | | `group_by` | (omitted) | Returns usage per language pair, across all API keys | | `group_by` | `key` | Returns usage per language pair and API key | | `aggregate_by` | `period` (default) | Returns totals over the entire date range | | `aggregate_by` | `day` | Returns one row per UTC day | `group_by` accepts a comma-separated list of dimensions. Currently `key` is the only supported value. Support for additional dimensions may be added in a future update. The two parameters combine: `group_by=key&aggregate_by=day` returns one row per language pair, API key, and day. ## Response structure The response contains a `language_pair_usage_report` object with the following fields: | **Field** | **Description** | | :- | :- | | `group_by` | The dimensions used for grouping (for example `["key"]`). Omitted if the request has no `group_by` | | `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` | Page number of the next page of results. `null` on the last page | | `language_pair_usages` | Array of usage entries, one per language pair (and per API key and day, depending on the request) | Each entry in `language_pair_usages` includes: * `source_language` and `target_language`: the language pair * `api_key` and `api_key_label`: the masked API key and its label, returned only when `group_by` includes `key` * `usage_date`: the day the usage was recorded (ISO 8601 datetime), returned only when `aggregate_by` is `day` * `usage`: usage split by service type Usage for API keys that are no longer on the account is returned with `api_key` set to `-` and `api_key_label` set to `unknown`. ### Usage breakdown | **Field** | **Description** | | :- | :- | | `total_characters` | Combined character usage across character-based services | | `text_translation_characters` | Characters used for text translation | | `document_translation_characters` | Characters used for document translation | | `text_improvement_characters` | Characters used for text improvement (rephrasing) | | `speech_to_text_minutes` | Minutes of speech-to-text usage, rounded to two decimal places | | `speech_to_speech_minutes` | Minutes of speech-to-speech usage, rounded to two decimal places | Voice usage is reported in minutes and is not included in `total_characters`, which covers character-based services only. ## Pagination Results are paginated. `next_page` is the page number to send as the `page` parameter to retrieve the following page. It is `null` on the last page. ## Example The following request retrieves daily usage per language pair and API key for a two-week range. ```bash theme={null} curl "https://api.deepl.com/v2/admin/analytics/language-pairs?start_date=2026-10-01&end_date=2026-10-14&group_by=key&aggregate_by=day" \ -H "Authorization: DeepL-Auth-Key YOUR_ADMIN_KEY" ``` The response contains one entry per language pair, API key, and day. This example shows a single entry: ```json theme={null} { "language_pair_usage_report": { "group_by": ["key"], "aggregate_by": "day", "start_date": "2026-10-01T00:00:00", "end_date": "2026-10-14T00:00:00", "next_page": null, "language_pair_usages": [ { "source_language": "en", "target_language": "ja", "api_key": "6909****92c8", "api_key_label": "Production key", "usage_date": "2026-10-02T00:00:00Z", "usage": { "total_characters": 120400, "text_translation_characters": 100000, "document_translation_characters": 20400, "text_improvement_characters": 0, "speech_to_text_minutes": 0, "speech_to_speech_minutes": 0 } } ] } } ``` > [!TIP] > > For a one-off download of language pair data, use the [language pair-level CSV export](https://developers.deepl.com/docs/admin/retrieving-usage-data.md#csv-export) in your account. ## OpenAPI ````yaml get /v2/admin/analytics/language-pairs 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.16.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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document * `vtt` - WebVTT Subtitle Document * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document * `yaml / yml` - YAML Document * `properties` - Java Properties Document * `strings` - iOS/macOS Strings Document * `md / markdown` - Markdown Document * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format * `zip` - SCORM Package (e-learning content) * `odt` - OpenDocument Text Document * `rtf` - Rich Text Format Document * `resx` - .NET Resource Document * `jpeg` / `jpg` / `png` - Image - 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: ManageSpokenTerms description: >- The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections. Spoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases, such as company names, acronyms, and product names, are transcribed correctly. A collection contains one or more term lists, each holding terms for a single language, and is applied to a voice session via the `spoken_terms_id` parameter. - 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.) For text translation, if you omit `source_lang`, DeepL detects the source language and applies the dictionary for the detected language pair. Document translation with a glossary requires `source_lang`. 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: ManageStyleProfiles description: >- The style profile endpoints allow you to create, inspect, edit and delete style profiles. A style profile bundles glossaries, style rule lists and translation memories under one ID. Pass its `style_profile_id` in a translation request instead of the individual customization parameters. Every component list is optional, and you can link components later with an update. A style profile can reference at most one style rule list per target language and at most one translation memory per source language. With `glossary_priority_order_enabled`, the order of the glossary IDs decides which glossary wins when two of them define the same source term. Deleting a style profile does not delete the glossaries, style rule lists and translation memories it links. Deleting one of those components removes it from every style profile that links it. - name: MetaInformation description: Information about API usage and value ranges - name: TranslationMemories description: >- The translation memory endpoints allow you to manage your account's translation memories, used to store and reuse previously created translations. You can list and retrieve translation memories, page through their stored segments, create one by importing a TMX file, export one back to TMX, and delete one. Editing the contents of an existing translation memory is not supported; import a new one instead. Importing and exporting run as background jobs. Create the job, then poll `GET /v3/translation_memories/jobs/{job_id}` until it reports `completed`. 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). A translation request fails with `404` if the translation memory does not exist or does not cover the requested language pair. - 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: >- **Beta.** Retrieve a quality evaluation report for a document DeepL has translated. Reports are requested with `enable_quality_evaluation` on `POST /v2/document` and polled here. A report lists 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/language-pairs: get: tags: - AdminApi summary: Get language pair usage statistics as an admin description: >- Retrieve usage statistics broken down by source and target language pair within a specified date range. Optionally group results by API key and aggregate them by day or over the entire period. Results are paginated; `next_page` in the response is the page number to send as `page` to retrieve the following page. Language pair-level data is available only to API Enterprise accounts and to API Pro accounts that have it enabled. For other accounts the request succeeds and returns an empty `language_pair_usages` array. operationId: adminGetLanguagePairAnalytics parameters: - name: start_date in: query required: true description: >- Start date for the usage report (ISO 8601 date format). Must not be after the current UTC day, and must fall within the supported lookback window. See [Get language pair usage analytics](/api-reference/admin-api/get-language-pair-usage-analytics#date-range). schema: type: string format: date example: '2026-10-01' - 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-10-14' - name: group_by in: query required: false description: >- Optional comma-separated list of dimensions to group usage by. Currently `key` is the only supported value: * `key` - Group by API key If omitted, usage is not split by API key. schema: type: string example: key - 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 UTC day schema: type: string enum: - period - day default: period example: day - name: page in: query required: false description: >- Page number of the results to return. `next_page` in the response holds the page number of the following page. schema: type: integer example: 2 responses: '200': description: The language pair usage statistics for the specified date range. headers: X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' content: application/json: schema: $ref: '#/components/schemas/LanguagePairUsageReport' examples: groupedByKeyAndDay: summary: Usage grouped by API key and aggregated by day value: language_pair_usage_report: group_by: - key aggregate_by: day start_date: '2026-10-01T00:00:00' end_date: '2026-10-14T00:00:00' next_page: null language_pair_usages: - source_language: en target_language: ja api_key: 6909****92c8 api_key_label: Production key usage_date: '2026-10-02T00:00:00Z' usage: total_characters: 120400 text_translation_characters: 100000 document_translation_characters: 20400 text_improvement_characters: 0 speech_to_text_minutes: 0 speech_to_speech_minutes: 0 - source_language: en target_language: ja api_key: '-' api_key_label: unknown usage_date: '2026-10-02T00:00:00Z' usage: total_characters: 250 text_translation_characters: 250 document_translation_characters: 0 text_improvement_characters: 0 speech_to_text_minutes: 0 speech_to_speech_minutes: 0 periodTotals: summary: Usage over the entire period, not grouped value: language_pair_usage_report: aggregate_by: period start_date: '2026-10-01T00:00:00' end_date: '2026-10-14T00:00:00' next_page: null language_pair_usages: - source_language: en target_language: ja usage: total_characters: 120650 text_translation_characters: 100250 document_translation_characters: 20400 text_improvement_characters: 0 speech_to_text_minutes: 0 speech_to_speech_minutes: 0 noLanguagePairData: summary: Account without language pair-level data value: language_pair_usage_report: aggregate_by: period start_date: '2026-10-01T00:00:00' end_date: '2026-10-14T00:00:00' next_page: null language_pair_usages: [] '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: oneOf: - type: object description: Returned when the date range is rejected. properties: message: type: string description: Error message describing the issue. - type: object description: Returned when a query parameter fails validation. properties: type: type: string title: type: string status: type: integer errors: type: object description: Validation messages, keyed by parameter name. additionalProperties: type: array items: type: string traceId: type: string examples: startDateInFuture: summary: start_date after the current UTC day value: message: >- Bad request. Reason: start_date must not be after the current UTC day invalidGroupBy: summary: Invalid group_by parameter value value: type: https://tools.ietf.org/html/rfc9110#section-15.5.1 title: One or more validation errors occurred. status: 400 errors: group_by: - >- Value for 'group_by' not supported. Allowed: 'key'. The parameter can be omitted. traceId: 00-0123456789abcdef0123456789abcdef-0123456789abcdef-01 '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: LanguagePairUsageReport: type: object description: The response for admin language pair usage statistics. properties: language_pair_usage_report: $ref: '#/components/schemas/LanguagePairUsageReportData' LanguagePairUsageReportData: type: object description: >- Contains the detailed language pair usage statistics for the specified date range. properties: group_by: type: array description: >- The dimensions the usage is grouped by. Omitted when the request has no `group_by`. items: type: string enum: - key example: - key 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-10-01T00:00:00' end_date: type: string format: date-time description: End date of the usage report period. example: '2026-10-14T00:00:00' next_page: type: integer nullable: true description: Page number of the next page of results. Null on the last page. example: 2 language_pair_usages: type: array description: >- List of usage entries, one per language pair (and per API key and day, depending on the request). Empty if the account has no language pair-level data. items: $ref: '#/components/schemas/LanguagePairUsageItem' 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 InfrastructureErrorResponse: description: > Error body returned by DeepL's edge infrastructure for failures that occur before a request reaches the API itself. The message is nested under `error`, unlike the application-level `ErrorResponse`. Clients that parse error bodies should handle both shapes. type: object required: - error properties: error: type: object required: - message properties: message: type: string description: A human-readable description of the error. example: Bad Gateway. LanguagePairUsageItem: type: object description: Usage statistics for a specific source and target language pair. properties: source_language: type: string description: The source language of the language pair. example: en target_language: type: string description: The target language of the language pair. example: ja api_key: type: string description: >- Masked API key identifier. Only returned when `group_by` includes `key`. `-` for keys that are no longer on the account. example: 6909****92c8 api_key_label: type: string description: >- Label associated with the API key. Only returned when `group_by` includes `key`. `unknown` for keys that are no longer on the account. example: Production key usage_date: type: string format: date-time description: >- The day the usage was recorded. Only returned when `aggregate_by` is `day`. example: '2026-10-02T00:00:00Z' usage: $ref: '#/components/schemas/LanguagePairUsageBreakdown' LanguagePairUsageBreakdown: type: object description: Breakdown of usage by category for a language pair. properties: total_characters: type: integer description: > Total number of characters used across character-based services. Voice usage is reported in minutes and is not included in this total. example: 120400 text_translation_characters: type: integer description: Number of characters used for text translation. example: 100000 document_translation_characters: type: integer description: Number of characters used for document translation. example: 20400 text_improvement_characters: type: integer description: Number of characters used for text improvement. example: 0 speech_to_text_minutes: type: number description: >- Duration of speech-to-text usage in minutes, rounded to two decimal places. example: 0 speech_to_speech_minutes: type: number description: >- Duration of speech-to-speech usage in minutes, rounded to two decimal places. 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. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/InfrastructureErrorResponse' 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 ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.