The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

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
eventsone of[]required

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/events' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "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-04-12T21:04:01.096Z",
        "type": "page_view"
      }
    ]
  }'
No Content

Events have been tracked.

Query site events

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
selectone of[]optional

whereall of[]optional

groupByone of[]optional

orderobjectoptional

rangestring · enumrequiredAvailable options:
limitinteger · min: 1 · max: 1000optionalDefault: 1000
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "select": [
      {
        "column": "datetime",
        "interval": "hour"
      }
    ],
    "where": [
      {
        "column": "datetime",
        "values": [
          "2025-04-12T21:04:01.096Z"
        ]
      },
      {
        "operator": "in"
      }
    ],
    "groupBy": [
      {
        "column": "datetime",
        "interval": "hour"
      }
    ],
    "order": {
      "by": {
        "column": "datetime",
        "interval": "hour"
      },
      "direction": "asc"
    },
    "range": "lastYear",
    "limit": 1
  }'
{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2025-04-12T21:04:01.096Z"
      ]
    }
  ]
}

Aggregated events in the site.

List a site visitor segments

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "title": "text",
      "claims": {
        "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
      },
      "events": 1,
      "visitors": 1,
      "sessions": 1
    }
  ]
}

List of visitor segments in the site.

Was this helpful?