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. A result holds at most limit rows; when more match, pass its next.page back as page to fetch the rest.

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
pagestringOptional

The next.page value of a previous result, to fetch the rows that follow it. Send the rest of the query unchanged. Relative ranges stay fixed to the time of the first page, but events recorded while paging can still move rows between pages.

Responses
200

Aggregated events in the site.

application/json
countnumberOptional

Total count of objects in the list

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: 313

{
  "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,
  "page": "text"
}
200

Aggregated events in the site.

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2026-01-01T00:00:00.000Z"
      ]
    }
  ]
}

Last updated

Was this helpful?

Powered by GitBook