Skip to content

Commit 4efb269

Browse files
authored
Merge pull request #487 from DeepL/docs/admin-api-language-pair-analytics
docs(admin): add language pair usage analytics endpoint
2 parents 0c537c7 + 77b831d commit 4efb269

7 files changed

Lines changed: 827 additions & 5 deletions

File tree

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
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

Comments
 (0)