From 0337871622c218540c797254ed69f628146c08e8 Mon Sep 17 00:00:00 2001
From: April Dianne Santos Matias <april.matias@deepl.com>
Date: Thu, 21 May 2026 14:52:24 +0200
Subject: [PATCH 1/2] Update aggregateByDay example

---
 .../get-custom-tag-usage-analytics.mdx        |  1 +
 api-reference/openapi.yaml                    | 22 ++++++++++++++-----
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/api-reference/admin-api/get-custom-tag-usage-analytics.mdx b/api-reference/admin-api/get-custom-tag-usage-analytics.mdx
index e93b5cc..aebe052 100644
--- a/api-reference/admin-api/get-custom-tag-usage-analytics.mdx
+++ b/api-reference/admin-api/get-custom-tag-usage-analytics.mdx
@@ -32,6 +32,7 @@ The response contains a `custom_tag_usage_report` object with the following fiel
 
 Each entry in `usage` includes:
 - `custom_tag`: the tag identifier
+- `usage_date`: the day the usage was recorded (ISO 8601 datetime). Only returned when `aggregate_by` is `day`
 - `breakdown`: character counts split by service type
 
 ### Usage breakdown
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index 107b856..c6969b1 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -293,14 +293,21 @@ paths:
                   value:
                     custom_tag_usage_report:
                       aggregate_by: "day"
-                      start_date: "2026-05-17T00:00:00"
-                      end_date: "2026-05-18T00:00:00"
-                      next_page: 2
+                      start_date: "2026-05-03T00:00:00"
+                      end_date: "2026-05-15T00:00:00"
+                      next_page: null
                       usage:
                       - custom_tag: "example-custom-tag"
+                        usage_date: "2026-05-04T00:00:00Z"
+                        breakdown:
+                          total_characters: 380
+                          text_translation_characters: 380
+                          text_improvement_characters: 0
+                      - custom_tag: "example-custom-tag"
+                        usage_date: "2026-05-11T00:00:00Z"
                         breakdown:
-                          total_characters: 190
-                          text_translation_characters: 190
+                          total_characters: 595
+                          text_translation_characters: 595
                           text_improvement_characters: 0
         400:
           description: Bad request. Please check error message and your parameters.
@@ -5883,6 +5890,11 @@ components:
           type: string
           description: The custom tag identifier.
           example: "example-custom-tag"
+        usage_date:
+          type: string
+          format: date-time
+          description: The day the usage was recorded. Only returned when `aggregate_by` is `day`.
+          example: "2026-05-04T00:00:00Z"
         breakdown:
           $ref: '#/components/schemas/CustomTagBreakdown'
     CustomTagBreakdown:

From 803421e2494f3e7708df0e8208c06db0c0daca5b Mon Sep 17 00:00:00 2001
From: seekuehe <8804248+seekuehe@users.noreply.github.com>
Date: Thu, 21 May 2026 12:55:39 +0000
Subject: [PATCH 2/2] chore: update OpenAPI JSON files from YAML sources

---
 api-reference/openapi.json | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/api-reference/openapi.json b/api-reference/openapi.json
index b2deb4d..ff5211c 100644
--- a/api-reference/openapi.json
+++ b/api-reference/openapi.json
@@ -341,15 +341,25 @@
                     "value": {
                       "custom_tag_usage_report": {
                         "aggregate_by": "day",
-                        "start_date": "2026-05-17T00:00:00",
-                        "end_date": "2026-05-18T00:00:00",
-                        "next_page": 2,
+                        "start_date": "2026-05-03T00:00:00",
+                        "end_date": "2026-05-15T00:00:00",
+                        "next_page": null,
                         "usage": [
                           {
                             "custom_tag": "example-custom-tag",
+                            "usage_date": "2026-05-04T00:00:00Z",
+                            "breakdown": {
+                              "total_characters": 380,
+                              "text_translation_characters": 380,
+                              "text_improvement_characters": 0
+                            }
+                          },
+                          {
+                            "custom_tag": "example-custom-tag",
+                            "usage_date": "2026-05-11T00:00:00Z",
                             "breakdown": {
-                              "total_characters": 190,
-                              "text_translation_characters": 190,
+                              "total_characters": 595,
+                              "text_translation_characters": 595,
                               "text_improvement_characters": 0
                             }
                           }
@@ -7864,6 +7874,12 @@
             "description": "The custom tag identifier.",
             "example": "example-custom-tag"
           },
+          "usage_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The day the usage was recorded. Only returned when `aggregate_by` is `day`.",
+            "example": "2026-05-04T00:00:00Z"
+          },
           "breakdown": {
             "$ref": "#/components/schemas/CustomTagBreakdown"
           }