Query a site's analytics events

Runs an aggregation query over a published site's Insights events, grouped and filtered over a time range. Use it to answer analytics questions about how visitors engage with a site's documentation: page views, visitors, searches, referrers, and broken URLs (404s). A 404 is a page_view or search_open_result event whose page is null, in the site display context; filter eventPageNotFoundType not in conditional to leave out 404s that adaptive content explains. Group by datetime for a trend over time and by urlPath for the top broken URLs.

Available in MCP

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

siteIdstringRequired

The unique id of the site

Body

rangeone ofRequired

string · enumOptionalPossible values:

or

limitinteger · min: 1 · max: 1000OptionalDefault: 1000

Responses

200

Aggregated events in the site.

application/json

post/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate

POST /v1/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 299

{
  "select": [
    {
      "column": "datetime",
      "interval": "hour"
    }
  ],
  "where": [
    {
      "column": "datetime",
      "values": [
        "2026-01-01T00:00:00.000Z"
      ]
    },
    {
      "operator": "in"
    }
  ],
  "groupBy": [
    {
      "column": "datetime",
      "interval": "hour"
    }
  ],
  "order": {
    "by": {
      "column": "datetime",
      "interval": "hour"
    },
    "direction": "asc"
  },
  "range": "yearToDate",
  "limit": 1000
}

200

Aggregated events in the site.

{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2026-01-01T00:00:00.000Z"
      ]
    }
  ]
}