Skip to content

Commit acb2582

Browse files
seekueheseekuehe
committed
Add admin analytics endpoint
1 parent 6ccdd8c commit acb2582

4 files changed

Lines changed: 613 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ The major and minor version numbers reflect changes to the DeepL API
99
number is used only for corrections to the OpenAPI specification, for example:
1010
typos, schema fixes, or adding examples.
1111

12+
## [3.5.0] - 2025-10-27
13+
### Added
14+
* Add new endpoint `v2/admin/analytics` which enables admins to retrieve usage statistics across their organization
15+
1216
## [3.4.2] - 2025-10-06
1317
### Added
1418
* Latin American Spanish (`ES-419`) is now supported as a target language option for
@@ -241,7 +245,7 @@ keys within an organization.
241245
## [2.0.0]
242246
Initial release of the OpenAPI specification.
243247

244-
248+
[3.5.0]: https://github.com/DeepLcom/openapi/compare/v3.4.2...v3.5.0
245249
[3.4.2]: https://github.com/DeepLcom/openapi/compare/v3.4.1...v3.4.2
246250
[3.4.1]: https://github.com/DeepLcom/openapi/compare/v3.4.0...v3.4.1
247251
[3.4.0]: https://github.com/DeepLcom/openapi/compare/v3.3.1...v3.4.0

‎openapi.json‎

Lines changed: 248 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"name": "DeepL - Contact us",
99
"url": "https://www.deepl.com/contact-us"
1010
},
11-
"version": "3.4.2"
11+
"version": "3.5.0"
1212
},
1313
"externalDocs": {
1414
"description": "DeepL Pro - Plans and pricing",
@@ -2494,6 +2494,156 @@
24942494
}
24952495
]
24962496
}
2497+
},
2498+
"/v2/admin/analytics": {
2499+
"get": {
2500+
"tags": [
2501+
"AdminApi"
2502+
],
2503+
"summary": "Get usage statistics as an admin",
2504+
"operationId": "adminGetAnalytics",
2505+
"description": "Retrieve usage statistics for the organization within a specified date range.\nOptionally group the results by API key or by API key and day.",
2506+
"parameters": [
2507+
{
2508+
"name": "start_date",
2509+
"in": "query",
2510+
"required": true,
2511+
"description": "Start date for the usage report (ISO 8601 date format).",
2512+
"schema": {
2513+
"type": "string",
2514+
"format": "date"
2515+
},
2516+
"example": "2025-09-29"
2517+
},
2518+
{
2519+
"name": "end_date",
2520+
"in": "query",
2521+
"required": true,
2522+
"description": "End date for the usage report (ISO 8601 date format).",
2523+
"schema": {
2524+
"type": "string",
2525+
"format": "date"
2526+
},
2527+
"example": "2025-10-01"
2528+
},
2529+
{
2530+
"name": "group_by",
2531+
"in": "query",
2532+
"required": false,
2533+
"description": "Optional parameter to group usage statistics. Possible values:\n * `key` - Group by API key\n * `key_and_day` - Group by API key and usage date",
2534+
"schema": {
2535+
"type": "string",
2536+
"enum": [
2537+
"key",
2538+
"key_and_day"
2539+
]
2540+
},
2541+
"example": "key_and_day"
2542+
}
2543+
],
2544+
"responses": {
2545+
"200": {
2546+
"description": "The usage statistics for the specified date range.",
2547+
"content": {
2548+
"application/json": {
2549+
"schema": {
2550+
"$ref": "#/components/schemas/AdminUsageReport"
2551+
},
2552+
"examples": {
2553+
"withGrouping": {
2554+
"summary": "Usage report grouped by key and day",
2555+
"value": {
2556+
"usage_report": {
2557+
"total_usage": {
2558+
"total_characters": 9619,
2559+
"text_translation_characters": 4892,
2560+
"document_translation_characters": 0,
2561+
"text_improvement_characters": 4727
2562+
},
2563+
"group_by": "key_and_day",
2564+
"start_date": "2025-09-29T00:00:00",
2565+
"end_date": "2025-10-01T00:00:00",
2566+
"grouped_usage": [
2567+
{
2568+
"api_key": "dc88****3a2c",
2569+
"api_key_label": "Staging API Key",
2570+
"usage_date": "2025-09-29T00:00:00Z",
2571+
"usage": {
2572+
"total_characters": 315,
2573+
"text_translation_characters": 159,
2574+
"document_translation_characters": 0,
2575+
"text_improvement_characters": 156
2576+
}
2577+
}
2578+
]
2579+
}
2580+
}
2581+
},
2582+
"withoutGrouping": {
2583+
"summary": "Usage report without grouping",
2584+
"value": {
2585+
"usage_report": {
2586+
"total_usage": {
2587+
"total_characters": 9619,
2588+
"text_translation_characters": 4892,
2589+
"document_translation_characters": 0,
2590+
"text_improvement_characters": 4727
2591+
},
2592+
"start_date": "2025-09-29T00:00:00",
2593+
"end_date": "2025-10-01T00:00:00"
2594+
}
2595+
}
2596+
}
2597+
}
2598+
}
2599+
}
2600+
},
2601+
"400": {
2602+
"description": "Bad request. Please check error message and your parameters.",
2603+
"content": {
2604+
"application/json": {
2605+
"schema": {
2606+
"type": "object",
2607+
"properties": {
2608+
"message": {
2609+
"type": "string",
2610+
"description": "Error message describing the issue."
2611+
}
2612+
}
2613+
},
2614+
"examples": {
2615+
"dateRangeExceeded": {
2616+
"summary": "Date range exceeds maximum allowed",
2617+
"value": {
2618+
"message": "Bad request. Reason: Date range cannot exceed 366 days"
2619+
}
2620+
},
2621+
"invalidGroupBy": {
2622+
"summary": "Invalid group_by parameter value",
2623+
"value": {
2624+
"message": "Value for 'group_by' not supported. Allowed: '', 'key', 'key_and_day'."
2625+
}
2626+
}
2627+
}
2628+
}
2629+
}
2630+
},
2631+
"403": {
2632+
"$ref": "#/components/responses/Forbidden"
2633+
},
2634+
"404": {
2635+
"$ref": "#/components/responses/NotFound"
2636+
},
2637+
"500": {
2638+
"$ref": "#/components/responses/InternalServerError"
2639+
}
2640+
},
2641+
"security": [
2642+
{
2643+
"auth_header": []
2644+
}
2645+
]
2646+
}
24972647
}
24982648
},
24992649
"components": {
@@ -3444,6 +3594,103 @@
34443594
"prefer_enthusiastic",
34453595
"prefer_friendly"
34463596
]
3597+
},
3598+
"AdminUsageReport": {
3599+
"type": "object",
3600+
"description": "The response for admin usage statistics.",
3601+
"properties": {
3602+
"usage_report": {
3603+
"$ref": "#/components/schemas/AdminUsageReportData"
3604+
}
3605+
}
3606+
},
3607+
"AdminUsageReportData": {
3608+
"type": "object",
3609+
"description": "Contains the detailed usage statistics for the specified date range.",
3610+
"properties": {
3611+
"total_usage": {
3612+
"$ref": "#/components/schemas/UsageBreakdown"
3613+
},
3614+
"start_date": {
3615+
"type": "string",
3616+
"format": "date-time",
3617+
"description": "Start date of the usage report period.",
3618+
"example": "2025-09-29T00:00:00"
3619+
},
3620+
"end_date": {
3621+
"type": "string",
3622+
"format": "date-time",
3623+
"description": "End date of the usage report period.",
3624+
"example": "2025-10-01T00:00:00"
3625+
},
3626+
"group_by": {
3627+
"type": "string",
3628+
"description": "The grouping method used, if any.",
3629+
"enum": [
3630+
"key",
3631+
"key_and_day"
3632+
],
3633+
"example": "key_and_day"
3634+
},
3635+
"grouped_usage": {
3636+
"type": "array",
3637+
"description": "Array of usage statistics grouped by the specified criteria. Only present when group_by parameter is provided.",
3638+
"items": {
3639+
"$ref": "#/components/schemas/GroupedUsageItem"
3640+
}
3641+
}
3642+
}
3643+
},
3644+
"UsageBreakdown": {
3645+
"type": "object",
3646+
"description": "Breakdown of character usage by category.",
3647+
"properties": {
3648+
"total_characters": {
3649+
"type": "integer",
3650+
"description": "Total number of characters used.",
3651+
"example": 9619
3652+
},
3653+
"text_translation_characters": {
3654+
"type": "integer",
3655+
"description": "Number of characters used for text translation.",
3656+
"example": 4892
3657+
},
3658+
"document_translation_characters": {
3659+
"type": "integer",
3660+
"description": "Number of characters used for document translation.",
3661+
"example": 0
3662+
},
3663+
"text_improvement_characters": {
3664+
"type": "integer",
3665+
"description": "Number of characters used for text improvement.",
3666+
"example": 4727
3667+
}
3668+
}
3669+
},
3670+
"GroupedUsageItem": {
3671+
"type": "object",
3672+
"description": "Usage statistics for a specific API key and optionally a specific date.",
3673+
"properties": {
3674+
"api_key": {
3675+
"type": "string",
3676+
"description": "Masked API key identifier.",
3677+
"example": "db96****cb2c"
3678+
},
3679+
"api_key_label": {
3680+
"type": "string",
3681+
"description": "Label associated with the API key.",
3682+
"example": "DeepL API Key Prod"
3683+
},
3684+
"usage_date": {
3685+
"type": "string",
3686+
"format": "date-time",
3687+
"description": "The usage date. Only present when group_by is \"key_and_day\".",
3688+
"example": "2025-09-29T00:00:00Z"
3689+
},
3690+
"usage": {
3691+
"$ref": "#/components/schemas/UsageBreakdown"
3692+
}
3693+
}
34473694
}
34483695
}
34493696
}

0 commit comments

Comments
 (0)