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

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

Responses

204

Events have been tracked.

post

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

{
  "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",
        "siteSection": "text",
        "siteSpace": "text",
        "siteShareKey": "text",
        "space": "text",
        "revision": "text",
        "page": "text"
      },
      "timestamp": "2025-08-26T20:44:16.148Z",
      "type": "page_view"
    }
  ]
}

204

Events have been tracked.

No content

Query site events

post

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

rangeone ofRequired

string · enumOptionalPossible values:

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

Responses

200

Aggregated events in the site.

application/json

post

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": [
        "2025-08-26T20:44:16.148Z"
      ]
    },
    {
      "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": [
        "2025-08-26T20:44:16.148Z"
      ]
    }
  ]
}

List a site visitor segments

get

Authorizations

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

Responseall of

get

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
    }
  ]
}

Was this helpful?

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: 453 { "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", "siteSection": "text", "siteSpace": "text", "siteShareKey": "text", "space": "text", "revision": "text", "page": "text" }, "timestamp": "2025-08-26T20:44:16.148Z", "type": "page_view" } ] }

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": [ "2025-08-26T20:44:16.148Z" ] }, { "operator": "in" } ], "groupBy": [ { "column": "datetime", "interval": "hour" } ], "order": { "by": { "column": "datetime", "interval": "hour" }, "direction": "asc" }, "range": "lastYear", "limit": 1000 }

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