From b3f679a66911d8c5dad5ec999254b8abc8d9e3d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 18 May 2026 11:09:16 +0000 Subject: [PATCH] Document period field on DocumentInsight rollups Recent activity is now returned as daily rollups while older activity is aggregated into weekly rollups, exposed via a new period enum on the response payload. --- spec3.json | 14 +++++++++++--- spec3.yml | 23 +++++++++++++++++------ 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/spec3.json b/spec3.json index ec33c5f..8977426 100644 --- a/spec3.json +++ b/spec3.json @@ -2550,7 +2550,7 @@ "Documents" ], "summary": "Retrieve insights for a document", - "description": "Retrieve a chronologically sorted array of daily activity rollups (views, comments, reactions, revisions, editors) for a document. Insights must be enabled on the document. Defaults to the last 30 days when no date range is provided.", + "description": "Retrieve a chronologically sorted array of activity rollups (views, comments, reactions, revisions, editors) for a document. Recent activity is returned as daily rollups, while older activity is aggregated into weekly rollups. Insights must be enabled on the document. Defaults to the last 30 days when no date range is provided.", "requestBody": { "content": { "application/json": { @@ -9031,12 +9031,20 @@ }, "DocumentInsight": { "type": "object", - "description": "A daily rollup of activity counts for a document.", + "description": "A rollup of activity counts for a document over a daily or weekly period.", "properties": { "date": { "type": "string", "format": "date", - "description": "The UTC day the rollup represents." + "description": "The UTC day the rollup represents. For weekly rollups this is the first day (Monday) of the week." + }, + "period": { + "type": "string", + "description": "The length of time the rollup covers. Daily rollups are stored for recent activity, older rollups are aggregated into weekly buckets.", + "enum": [ + "day", + "week" + ] }, "viewCount": { "type": "integer", diff --git a/spec3.yml b/spec3.yml index 3f36cac..6f9c8ea 100644 --- a/spec3.yml +++ b/spec3.yml @@ -1886,10 +1886,11 @@ paths: tags: - Documents summary: Retrieve insights for a document - description: Retrieve a chronologically sorted array of daily activity - rollups (views, comments, reactions, revisions, editors) for a document. - Insights must be enabled on the document. Defaults to the last 30 days - when no date range is provided. + description: Retrieve a chronologically sorted array of activity rollups + (views, comments, reactions, revisions, editors) for a document. Recent + activity is returned as daily rollups, while older activity is + aggregated into weekly rollups. Insights must be enabled on the + document. Defaults to the last 30 days when no date range is provided. requestBody: content: application/json: @@ -6263,12 +6264,22 @@ components: format: date-time DocumentInsight: type: object - description: A daily rollup of activity counts for a document. + description: A rollup of activity counts for a document over a daily or weekly + period. properties: date: type: string format: date - description: The UTC day the rollup represents. + description: The UTC day the rollup represents. For weekly rollups this is + the first day (Monday) of the week. + period: + type: string + description: The length of time the rollup covers. Daily rollups are + stored for recent activity, older rollups are aggregated into + weekly buckets. + enum: + - day + - week viewCount: type: integer description: Total number of document views on this day.