---
title: "Retrieve insights for a document"
method: POST
path: "/documents.insights"
tags: ["Documents"]
---

# Retrieve insights for a document

`POST /documents.insights`

## Request

- Base URL: `https://app.getoutline.com/api`
- URL: `https://app.getoutline.com/api/documents.insights`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://app.getoutline.com/oauth/authorize`
    - Token URL: `https://app.getoutline.com/oauth/token` scopes: `read`, `write`

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.

## Request body

- object
  - `id` string, uuid, required: Unique identifier for the document.
  - `startDate` string, date-time: Start of the insights window (inclusive). Defaults to 30 days ago.
  - `endDate` string, date-time: End of the insights window (inclusive). Defaults to today.

## Response `200`

OK

- object
  - `data` DocumentInsight[]
    - `date` string, date: The UTC day the rollup represents. For weekly rollups this is the first day (Monday) of the week.
    - `period` 'day' | 'week': The length of time the rollup covers. Daily rollups are stored for recent activity, older rollups are aggregated into weekly buckets.
    - `viewCount` integer: Total number of document views on this day.
    - `viewerCount` integer: Number of unique viewers on this day.
    - `commentCount` integer: Total comments made on this day.
    - `reactionCount` integer: Total reactions added on this day.
    - `revisionCount` integer: Number of document revisions on this day.
    - `editorCount` integer: Number of unique editors on this day.

## Other responses

- `400`: The request failed one or more validations.
- `401`: The API key is missing or otherwise invalid.
- `403`: The current API key is not authorized to perform this action.
- `404`: The specified resource was not found.
- `429`: The request was rate limited.

## Changes

- **2026-05-19** `c87de6a302b0`: 1 info
  - added the optional property `data/items/period` to the response with the `200` status
- **2026-04-27** `e39f1589827c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/defaulr/apis/outline-api/changes/documents.insights/post.md)

---

[API](https://skmtc.dev/defaulr/apis/outline-api.md) - [All operations](https://skmtc.dev/defaulr/apis/outline-api/llms.txt) - [OpenAPI document](https://skmtc.dev/defaulr/apis/outline-api/revisions/5ddf01ffba84?raw)