Skip to content

Commit 68c5b52

Browse files
seekueheseekuehe
authored
Merge pull request #350 from DeepLcom/update-analytics-docs
Add custom tags analytics endpoint
2 parents 20e9905 + 1366f4f commit 68c5b52

7 files changed

Lines changed: 572 additions & 44 deletions

File tree

‎api-reference/admin-api/get-custom-tag-usage-analytics.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
openapi: get /v2/admin/analytics/custom-tags
3+
title: "Get custom tag usage analytics"
4+
---
5+
6+
## Date range
7+
8+
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.
9+
10+
## Aggregation
11+
12+
The optional `aggregate_by` parameter controls how usage is grouped:
13+
14+
| **Value** | **Description** |
15+
|:---|:---|
16+
| `period` (default) | Returns total usage per custom tag over the entire date range |
17+
| `day` | Returns usage per custom tag broken down by individual day |
18+
19+
Use `period` when you need a summary for billing or reporting. Use `day` when you need to analyze usage trends over time.
20+
21+
## Response structure
22+
23+
The response contains a `custom_tag_usage_report` object with the following fields:
24+
25+
| **Field** | **Description** |
26+
|:---|:---|
27+
| `aggregate_by` | The aggregation method used (`period` or `day`) |
28+
| `start_date` | Start of the reporting period (ISO 8601 datetime) |
29+
| `end_date` | End of the reporting period (ISO 8601 datetime) |
30+
| `next_page` | Integer cursor for the next page of results. `null` if there are no further pages |
31+
| `usage` | Array of usage entries, one per custom tag |
32+
33+
Each entry in `usage` includes:
34+
- `custom_tag`: the tag identifier
35+
- `breakdown`: character counts split by service type
36+
37+
### Usage breakdown
38+
39+
| **Field** | **Description** |
40+
|:---|:---|
41+
| `total_characters` | Combined character usage across all services |
42+
| `text_translation_characters` | Characters used for text translation |
43+
| `text_improvement_characters` | Characters used for text improvement (rephrasing) |
44+
45+
<Warning>
46+
Custom tag data is supported only for text translation. Support for other request types will be added in a future update.
47+
</Warning>
48+
49+
## Pagination
50+
51+
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`.

‎api-reference/admin-api/get-usage-analytics.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,35 @@ openapi: get /v2/admin/analytics
33
title: "Get usage analytics"
44
---
55

6+
## Date range
7+
8+
Specify the reporting window using the required `start_date` and `end_date` parameters. Both support the following formats (all in UTC):
9+
10+
| **Format** | **Example** |
11+
|:---|:---|
12+
| `YYYY-MM-DD` | `2025-09-29` |
13+
| `YYYY-MM-DDTHH:MM:SS` | `2025-09-29T14:30:00` |
14+
15+
The maximum date range is 366 days.
16+
17+
## Grouping
18+
19+
The optional `group_by` parameter controls how results are organized:
20+
21+
| **Value** | **Description** |
22+
|:---|:---|
23+
| (default) | Returns total usage for the entire date range across all API keys |
24+
| `key` | Groups usage by individual API key, showing totals for each key over the date range |
25+
| `key_and_day` | Groups usage by both API key and day, providing daily breakdowns per key |
26+
27+
## Response structure
28+
29+
All responses include a breakdown of usage by service type:
30+
31+
| **Field** | **Description** |
32+
|:---|:---|
33+
| `total_characters` | Combined character usage across all services |
34+
| `text_translation_characters` | Characters used for text translation |
35+
| `document_translation_characters` | Characters used for document translation |
36+
| `text_improvement_characters` | Characters used for text improvement (rephrasing) |
37+
| `speech_to_text_minutes` | Duration of speech-to-text usage in minutes |

‎api-reference/admin-api/organization-usage-analytics.mdx‎

Lines changed: 24 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,38 @@
11
---
2-
title: "Accessing organization usage analytics"
2+
title: "Accessing usage analytics"
33
description: "Learn how admins can retrieve and analyze usage data across their organization."
44
public: true
55
---
66

7-
The Admin API allows admins to retrieve detailed usage statistics for their organization through the [Get usage analytics](/api-reference/admin-api/get-usage-analytics) endpoint.
7+
The Admin API provides two endpoints for monitoring usage across your organization:
88

9-
This analytics functionality enables you to:
10-
* Track character usage across your entire organization
11-
* Monitor usage by individual API keys
12-
* Analyze usage patterns over time
13-
* Generate reports for specific date ranges
14-
* Break down usage by service type (text translation, document translation, text improvement)
9+
- [Get usage analytics](/api-reference/admin-api/get-usage-analytics): retrieves total usage statistics, optionally grouped by API key or day
10+
- [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics): retrieves usage statistics broken down by custom tags
1511

16-
## Usage statistics endpoint
12+
## Organization usage
1713

18-
The analytics endpoint provides detailed usage information for a specified date range with flexible grouping options.
14+
The [Get usage analytics](/api-reference/admin-api/get-usage-analytics) endpoint returns usage statistics for a specified date range with flexible grouping options. It covers all services: text translation, document translation, text improvement, and speech-to-text.
1915

20-
### Date range queries
16+
## Custom tag usage
2117

22-
Retrieve usage statistics by specifying a start and end date. Both `start_date` and `end_date` parameters are required and support the following formats (all in UTC):
23-
* `YYYY-MM-DD` - Simple date format (e.g., `2025-09-29`)
24-
* `YYYY-MM-DDTHH:MM:SS` - Full datetime format (e.g., `2025-09-29T14:30:00`)
18+
Custom tags are an optional dimension for breaking down usage. If your organization wants to track consumption by team, project, or any other category, you can attach a single tag to individual API requests using the `X-DeepL-Reporting-Tag` header. Each request accepts one tag.
2519

26-
The maximum date range is 366 days.
20+
The [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics) endpoint only returns usage from tagged requests. Untagged requests are not included, so the results will reflect a subset of your organization's total usage unless all API requests are tagged.
2721

28-
### Grouping options
22+
```bash
23+
curl --request POST \
24+
--url https://api.deepl.com/v2/translate \
25+
--header 'Authorization: DeepL-Auth-Key YOUR_AUTH_KEY' \
26+
--header 'X-DeepL-Reporting-Tag: your-custom-tag' \
27+
--header 'Content-Type: application/json' \
28+
--data '{
29+
"text": ["Hello, world!"],
30+
"target_lang": "DE"
31+
}'
32+
```
2933

30-
The optional `group_by` parameter allows you to organize usage data in different ways:
31-
32-
* **No grouping** (default): Returns total usage for the entire date range across all API keys
33-
* **`key`**: Groups usage by individual API key, showing totals for each key over the entire date range
34-
* **`key_and_day`**: Groups usage by both API key and day, providing daily breakdowns for each key
35-
36-
### Usage breakdown
37-
38-
All responses include a breakdown of usage by service type:
39-
* **Total characters**: Combined usage across all services
40-
* **Text translation characters**: Characters used for text translation
41-
* **Document translation characters**: Characters used for document translation
42-
* **Text improvement characters**: Characters used for text improvement (rephrasing)
43-
* **Speech-to-text minutes**: Duration of speech-to-text usage in minutes
44-
45-
## Use cases
46-
47-
The account-level analytics endpoint is particularly useful for:
48-
49-
* **Cost monitoring**: Track usage to stay within budget limits and forecast costs
50-
* **Resource allocation**: Identify which teams or projects (represented by API keys) are using the most resources
51-
* **Usage trends**: Analyze daily or weekly usage patterns to optimize resource planning
52-
* **Compliance and auditing**: Generate detailed usage reports for compliance requirements
53-
* **Performance tracking**: Monitor adoption and usage of different DeepL services within your organization
34+
<Warning>
35+
Custom tag data is currently supported for text translation. Support for additional request types will be added in a future update.
36+
</Warning>
5437

38+
Once tags are in place, query [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics) to retrieve usage broken down by tag.

0 commit comments

Comments
 (0)