DeepLcom · seekuehe · May 20, 2026 · May 20, 2026 · May 20, 2026 · May 20, 2026
diff --git a/api-reference/admin-api/get-custom-tag-usage-analytics.mdx b/api-reference/admin-api/get-custom-tag-usage-analytics.mdx
@@ -0,0 +1,51 @@
+---
+openapi: get /v2/admin/analytics/custom-tags
+title: "Get custom tag usage analytics"
+---
+
+## 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
+- `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) |
+
+<Warning>
+Custom tag data is supported only for text translation. Support for other request types will be added in a future update.
+</Warning>
+
+## 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`.
diff --git a/api-reference/admin-api/get-usage-analytics.mdx b/api-reference/admin-api/get-usage-analytics.mdx
@@ -3,3 +3,35 @@ openapi: get /v2/admin/analytics
 title: "Get usage analytics"
 ---
 
+## Date range
+
+Specify the reporting window using the required `start_date` and `end_date` parameters. Both support the following formats (all in UTC):
+
+| **Format** | **Example** |
+|:---|:---|
+| `YYYY-MM-DD` | `2025-09-29` |
+| `YYYY-MM-DDTHH:MM:SS` | `2025-09-29T14:30:00` |
+
+The maximum date range is 366 days.
+
+## Grouping
+
+The optional `group_by` parameter controls how results are organized:
+
+| **Value** | **Description** |
+|:---|:---|
+| (default) | Returns total usage for the entire date range across all API keys |
+| `key` | Groups usage by individual API key, showing totals for each key over the date range |
+| `key_and_day` | Groups usage by both API key and day, providing daily breakdowns per key |
+
+## Response structure
+
+All responses include a breakdown of usage by service type:
+
+| **Field** | **Description** |
+|:---|:---|
+| `total_characters` | Combined character usage across all 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` | Duration of speech-to-text usage in minutes |
diff --git a/api-reference/admin-api/organization-usage-analytics.mdx b/api-reference/admin-api/organization-usage-analytics.mdx
@@ -1,54 +1,38 @@
 ---
-title: "Accessing organization usage analytics"
+title: "Accessing usage analytics"
 description: "Learn how admins can retrieve and analyze usage data across their organization."
 public: true
 ---
 
-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.
+The Admin API provides two endpoints for monitoring usage across your organization:
 
-This analytics functionality enables you to:
-* Track character usage across your entire organization
-* Monitor usage by individual API keys
-* Analyze usage patterns over time
-* Generate reports for specific date ranges
-* Break down usage by service type (text translation, document translation, text improvement)
+- [Get usage analytics](/api-reference/admin-api/get-usage-analytics): retrieves total usage statistics, optionally grouped by API key or day
+- [Get custom tag usage analytics](/api-reference/admin-api/get-custom-tag-usage-analytics): retrieves usage statistics broken down by custom tags
 
-## Usage statistics endpoint
+## Organization usage
 
-The analytics endpoint provides detailed usage information for a specified date range with flexible grouping options.
+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.
 
-### Date range queries
+## Custom tag usage
 
-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):
-* `YYYY-MM-DD` - Simple date format (e.g., `2025-09-29`)
-* `YYYY-MM-DDTHH:MM:SS` - Full datetime format (e.g., `2025-09-29T14:30:00`)
+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.
 
-The maximum date range is 366 days.
+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.
 
-### Grouping options
+```bash
+curl --request POST \
+  --url https://api.deepl.com/v2/translate \
+  --header 'Authorization: DeepL-Auth-Key YOUR_AUTH_KEY' \
+  --header 'X-DeepL-Reporting-Tag: your-custom-tag' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "text": ["Hello, world!"],
+    "target_lang": "DE"
+  }'
+```
 
-The optional `group_by` parameter allows you to organize usage data in different ways:
-
-* **No grouping** (default): Returns total usage for the entire date range across all API keys
-* **`key`**: Groups usage by individual API key, showing totals for each key over the entire date range
-* **`key_and_day`**: Groups usage by both API key and day, providing daily breakdowns for each key
-
-### Usage breakdown
-
-All responses include a breakdown of usage by service type:
-* **Total characters**: Combined usage across all 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**: Duration of speech-to-text usage in minutes
-
-## Use cases
-
-The account-level analytics endpoint is particularly useful for:
-
-* **Cost monitoring**: Track usage to stay within budget limits and forecast costs
-* **Resource allocation**: Identify which teams or projects (represented by API keys) are using the most resources
-* **Usage trends**: Analyze daily or weekly usage patterns to optimize resource planning
-* **Compliance and auditing**: Generate detailed usage reports for compliance requirements
-* **Performance tracking**: Monitor adoption and usage of different DeepL services within your organization
+<Warning>
+Custom tag data is currently supported for text translation. Support for additional request types will be added in a future update.
+</Warning>
 
+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.