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.

Last updated 5 days ago

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: 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": "2025-12-24T11:30:26.585Z",
      "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-12-24T11:30:26.585Z"
      ]
    },
    {
      "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
    }
  ]
}

Site insights

Track site events

Query site events

List a site visitor segments