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

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-05-14T01:51:39.262Z",
      "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

rangestring · enumRequiredAllowed values:

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

Responses

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

{
  "select": [
    {
      "column": "datetime",
      "interval": "hour"
    }
  ],
  "where": [
    {
      "column": "datetime",
      "values": [
        "2025-05-14T01:51:39.262Z"
      ]
    },
    {
      "operator": "in"
    }
  ],
  "groupBy": [
    {
      "column": "datetime",
      "interval": "hour"
    }
  ],
  "order": {
    "by": {
      "column": "datetime",
      "interval": "hour"
    },
    "direction": "asc"
  },
  "range": "lastYear",
  "limit": 1
}

200

Aggregated events in the site.

{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2025-05-14T01:51:39.262Z"
      ]
    }
  ]
}

List a site visitor segments

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

application/json

all ofOptional

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?