Site insights

Analyze traffic and engagement metrics for your docs site.

This API delivers insights about how visitors interact with your site, including page views and user engagement, helping you measure and optimize your content strategy.

Track site events

post

Authorizations

useruser-internaluser-staffuser-internal-or-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

Responses

204

Events have been tracked.

post

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

HTTPcURLJavaScriptPython

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

{
  "events": [
    {
      "session": {
        "visitorId": "text",
        "sessionId": "text",
        "cookies": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "ip": "text",
        "userAgent": "text",
        "language": "text",
        "referrer": null,
        "visitorAuthClaims": {
          "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
        }
      },
      "location": {
        "url": "https://example.com",
        "displayContext": "site",
        "siteSection": "text",
        "siteSpace": "text",
        "siteShareKey": "text",
        "space": "text",
        "revision": "text",
        "page": "text"
      },
      "timestamp": "2026-01-23T03:00:02.296Z",
      "type": "page_view"
    }
  ]
}

204

Events have been tracked.

No content

Query site events

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

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

HTTPcURLJavaScriptPython

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

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

200

Aggregated events in the site.

{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2026-01-23T03:00:02.296Z"
      ]
    }
  ]
}

List a site visitor segments

get

Authorizations

useruser-internaluser-staffuser-internal-or-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

List of visitor segments in the site.

application/json

get

/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of visitor segments in the site.

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "title": "text",
      "claims": {
        "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
      },
      "events": 1,
      "visitors": 1,
      "sessions": 1
    }
  ]
}