|
| 1 | +--- |
| 2 | +openapi: get /v2/admin/analytics/language-pairs |
| 3 | +title: "Get language pair usage analytics" |
| 4 | +description: "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." |
| 5 | +--- |
| 6 | + |
| 7 | +## Availability |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +If your admin key belongs to an account without language pair-level data, the request succeeds and returns an empty `language_pair_usages` array. |
| 12 | + |
| 13 | +## Date range |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +- `start_date` can't be after the current UTC day |
| 18 | +- `start_date` can't be more than 63 days before the current UTC day |
| 19 | + |
| 20 | +Requests that break either rule return a `400` error. |
| 21 | + |
| 22 | +Usage data is available up to and including the previous UTC calendar day, so that is the latest day `end_date` can include. |
| 23 | + |
| 24 | +## Grouping and aggregation |
| 25 | + |
| 26 | +Two optional parameters control how usage is organized. |
| 27 | + |
| 28 | +| **Parameter** | **Value** | **Description** | |
| 29 | +|:---|:---|:---| |
| 30 | +| `group_by` | (omitted) | Returns usage per language pair, across all API keys | |
| 31 | +| `group_by` | `key` | Returns usage per language pair and API key | |
| 32 | +| `aggregate_by` | `period` (default) | Returns totals over the entire date range | |
| 33 | +| `aggregate_by` | `day` | Returns one row per UTC day | |
| 34 | + |
| 35 | +`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. |
| 36 | + |
| 37 | +## Response structure |
| 38 | + |
| 39 | +The response contains a `language_pair_usage_report` object with the following fields: |
| 40 | + |
| 41 | +| **Field** | **Description** | |
| 42 | +|:---|:---| |
| 43 | +| `group_by` | The dimensions used for grouping (for example `["key"]`). Omitted if the request has no `group_by` | |
| 44 | +| `aggregate_by` | The aggregation method used (`period` or `day`) | |
| 45 | +| `start_date` | Start of the reporting period (ISO 8601 datetime) | |
| 46 | +| `end_date` | End of the reporting period (ISO 8601 datetime) | |
| 47 | +| `next_page` | Page number of the next page of results. `null` on the last page | |
| 48 | +| `language_pair_usages` | Array of usage entries, one per language pair (and per API key and day, depending on the request) | |
| 49 | + |
| 50 | +Each entry in `language_pair_usages` includes: |
| 51 | + |
| 52 | +- `source_language` and `target_language`: the language pair |
| 53 | +- `api_key` and `api_key_label`: the masked API key and its label, returned only when `group_by` includes `key` |
| 54 | +- `usage_date`: the day the usage was recorded (ISO 8601 datetime), returned only when `aggregate_by` is `day` |
| 55 | +- `usage`: usage split by service type |
| 56 | + |
| 57 | +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`. |
| 58 | + |
| 59 | +### Usage breakdown |
| 60 | + |
| 61 | +| **Field** | **Description** | |
| 62 | +|:---|:---| |
| 63 | +| `total_characters` | Combined character usage across character-based services | |
| 64 | +| `text_translation_characters` | Characters used for text translation | |
| 65 | +| `document_translation_characters` | Characters used for document translation | |
| 66 | +| `text_improvement_characters` | Characters used for text improvement (rephrasing) | |
| 67 | +| `speech_to_text_minutes` | Minutes of speech-to-text usage, rounded to two decimal places | |
| 68 | +| `speech_to_speech_minutes` | Minutes of speech-to-speech usage, rounded to two decimal places | |
| 69 | + |
| 70 | +Voice usage is reported in minutes and is not included in `total_characters`, which covers character-based services only. |
| 71 | + |
| 72 | +## Pagination |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +## Example |
| 77 | + |
| 78 | +The following request retrieves daily usage per language pair and API key for a two-week range. |
| 79 | + |
| 80 | +```bash |
| 81 | +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" \ |
| 82 | + -H "Authorization: DeepL-Auth-Key YOUR_ADMIN_KEY" |
| 83 | +``` |
| 84 | + |
| 85 | +The response contains one entry per language pair, API key, and day. This example shows a single entry: |
| 86 | + |
| 87 | +```json |
| 88 | +{ |
| 89 | + "language_pair_usage_report": { |
| 90 | + "group_by": ["key"], |
| 91 | + "aggregate_by": "day", |
| 92 | + "start_date": "2026-10-01T00:00:00", |
| 93 | + "end_date": "2026-10-14T00:00:00", |
| 94 | + "next_page": null, |
| 95 | + "language_pair_usages": [ |
| 96 | + { |
| 97 | + "source_language": "en", |
| 98 | + "target_language": "ja", |
| 99 | + "api_key": "6909****92c8", |
| 100 | + "api_key_label": "Production key", |
| 101 | + "usage_date": "2026-10-02T00:00:00Z", |
| 102 | + "usage": { |
| 103 | + "total_characters": 120400, |
| 104 | + "text_translation_characters": 100000, |
| 105 | + "document_translation_characters": 20400, |
| 106 | + "text_improvement_characters": 0, |
| 107 | + "speech_to_text_minutes": 0, |
| 108 | + "speech_to_speech_minutes": 0 |
| 109 | + } |
| 110 | + } |
| 111 | + ] |
| 112 | + } |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +<Tip> |
| 117 | +For a one-off download of language pair data, use the [language pair-level CSV export](/docs/admin/retrieving-usage-data#csv-export) in your account. |
| 118 | +</Tip> |
0 commit comments