# Site insights

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.

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

> Track site events

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-insights","description":"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.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]},{"user-internal":[]},{"user-staff":[]},{"user-internal-or-staff":[]},{"integration":[]},{"integration-installation":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"},"user-internal":{"type":"http","scheme":"bearer"},"user-staff":{"type":"http","scheme":"bearer"},"user-internal-or-staff":{"type":"http","scheme":"bearer"},"integration":{"type":"http","scheme":"bearer"},"integration-installation":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"SiteInsightsEvent":{"oneOf":[{"$ref":"#/components/schemas/SiteInsightsEventPageView"},{"$ref":"#/components/schemas/SiteInsightsEventPageMarkdownRequest"},{"$ref":"#/components/schemas/SiteInsightsEventSearchOpen"},{"$ref":"#/components/schemas/SiteInsightsEventSearchTypeQuery"},{"$ref":"#/components/schemas/SiteInsightsEventSearchOpenResult"},{"$ref":"#/components/schemas/SiteInsightsEventPagePostFeedback"},{"$ref":"#/components/schemas/SiteInsightsEventPagePostFeedbackComment"},{"$ref":"#/components/schemas/SiteInsightsEventAskQuestion"},{"$ref":"#/components/schemas/SiteInsightsEventAskView"},{"$ref":"#/components/schemas/SiteInsightsEventAskRateResponse"},{"$ref":"#/components/schemas/SiteInsightsEventLinkClick"},{"$ref":"#/components/schemas/SiteInsightsEventAPIClientOpen"},{"$ref":"#/components/schemas/SiteInsightsEventAPIClientRequest"},{"$ref":"#/components/schemas/SiteInsightsEventTrademarkClick"},{"$ref":"#/components/schemas/SiteInsightsEventAdClick"},{"$ref":"#/components/schemas/SiteInsightsEventAdDisplay"},{"$ref":"#/components/schemas/SiteInsightsEventLLMSRequest"},{"$ref":"#/components/schemas/SiteInsightsEventMCPRequest"},{"$ref":"#/components/schemas/SiteInsightsEventRSSRequest"}]},"SiteInsightsEventPageView":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["page_view"]}},"required":["type"]}]},"SiteInsightsEventBase":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SiteInsightsEventSession"},"location":{"$ref":"#/components/schemas/SiteInsightsEventLocation"},"timestamp":{"description":"Optional timestamp of the event. If not provided, the current timestamp will be used. Must be within 5 minutes of the current time.","$ref":"#/components/schemas/Timestamp"}},"required":["session","location"]},"SiteInsightsEventSession":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsSession"},{"type":"object","description":"Analytics info on the GitBook's site session.","properties":{"cookies":{"type":"object","description":"The visitors cookies.","additionalProperties":{"type":"string"}},"ip":{"type":"string","description":"IP address of the visitor.\nIf not defined, it'll default to the IP executing the request.\n"},"userAgent":{"type":"string","description":"User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n"},"language":{"type":["string","null"],"description":"Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n"},"referrer":{"description":"Referrer of the session","oneOf":[{"type":"null"},{"type":"string","enum":[""]},{"$ref":"#/components/schemas/URL"}]},"visitorAuthToken":{"type":["string","null"],"deprecated":true,"description":"Deprecated, use visitorAuthClaims instead."},"visitorAuthClaims":{"description":"Claims of the visitor.\nThis is used to identify the visitor with adaptive content.\n","$ref":"#/components/schemas/PlainObject"}},"required":["cookies","userAgent","language","referrer"]}]},"SiteInsightsSession":{"type":"object","description":"Identifiers for a GitBook site session, used for analytics and adaptive content.","properties":{"visitorId":{"type":"string","description":"GitBook's unique identifier of the visitor."},"sessionId":{"type":"string","description":"GitBook's unique identifier of the visitor's session."}},"required":["visitorId","sessionId"]},"URL":{"type":"string","format":"uri","maxLength":2048},"PlainObject":{"properties":{},"additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/PlainObject"},{"type":"string"},{"type":"boolean"},{"type":"number"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"boolean"},{"type":"number"},{"$ref":"#/components/schemas/PlainObject"}]}}]}},"SiteInsightsEventLocation":{"type":"object","description":"Location of the event.","properties":{"url":{"description":"URL of the location.","$ref":"#/components/schemas/URL"},"displayContext":{"description":"Whether the event was tracked on the site, the server, or an embed widget.","$ref":"#/components/schemas/SiteInsightsDisplayContext","default":"site"},"siteSection":{"type":["string","null"],"description":"ID of the concerned site section."},"siteSpace":{"type":["string","null"],"description":"ID of the concerned site space."},"siteShareKey":{"type":["string","null"],"description":"ID of the concerned site share key."},"space":{"type":["string","null"],"description":"ID of the concerned space."},"revision":{"type":["string","null"],"description":"ID of the concerned revision."},"page":{"type":["string","null"],"description":"ID of the concerned page."}},"required":["url","siteSection","siteSpace","siteShareKey","page","space","revision"]},"SiteInsightsDisplayContext":{"type":"string","description":"Context in which the event was recorded.","enum":["site","server","embed","mcp"]},"Timestamp":{"type":"string","format":"date-time"},"SiteInsightsEventPageMarkdownRequest":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["page_markdown_request"]}},"required":["type"]}]},"SiteInsightsEventSearchOpen":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["search_open"]}},"required":["type"]}]},"SiteInsightsEventSearchTypeQuery":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["search_type_query"]},"query":{"type":"string","description":"Query of the search."}},"required":["type","query"]}]},"SiteInsightsEventSearchOpenResult":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["search_open_result"]},"query":{"type":"string","description":"Query of the search."},"result":{"description":"Target of the opened search result.","oneOf":[{"type":"object","properties":{"spaceId":{"type":"string","description":"ID of the concerned space."},"pageId":{"type":"string","description":"ID of the concerned page."}},"required":["spaceId","pageId"]},{"type":"object","properties":{"recordId":{"type":"string","description":"ID of the concerned record."}},"required":["recordId"]}]}},"required":["type","query","result"]}]},"SiteInsightsEventPagePostFeedback":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["page_post_feedback"]},"feedback":{"type":"object","properties":{"rating":{"$ref":"#/components/schemas/PageFeedbackRating"}},"required":["rating"]}},"required":["type","feedback"]}]},"PageFeedbackRating":{"type":"string","enum":["bad","ok","good"]},"SiteInsightsEventPagePostFeedbackComment":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["page_post_feedback_comment"]},"feedback":{"type":"object","properties":{"rating":{"$ref":"#/components/schemas/PageFeedbackRating"},"comment":{"type":"string","minLength":1,"maxLength":512}},"required":["rating","comment"]}},"required":["type","feedback"]}]},"SiteInsightsEventAskQuestion":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["ask_question"]},"query":{"type":"string","description":"Question being asked."}},"required":["type","query"]}]},"SiteInsightsEventAskView":{"description":"Event when a user views the ask UI.","allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["ask_view"]}},"required":["type"]}]},"SiteInsightsEventAskRateResponse":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["ask_rate_response"]},"query":{"type":"string","description":"Question asked."},"rating":{"type":"integer","enum":[1,-1]},"responseId":{"type":"string","description":"ID of the AI response."}},"required":["type","query","rating","responseId"]}]},"SiteInsightsEventLinkClick":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["link_click"]},"link":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/ContentRef"},"position":{"$ref":"#/components/schemas/SiteInsightsLinkPosition"}},"required":["target","position"]}},"required":["type","link"]}]},"ContentRef":{"description":"A relative reference to content in GitBook.","oneOf":[{"$ref":"#/components/schemas/ContentRefFile"},{"$ref":"#/components/schemas/ContentRefURL"},{"$ref":"#/components/schemas/ContentRefPage"},{"$ref":"#/components/schemas/ContentRefAnchor"},{"$ref":"#/components/schemas/ContentRefUser"},{"$ref":"#/components/schemas/ContentRefCollection"},{"$ref":"#/components/schemas/ContentRefSpace"},{"$ref":"#/components/schemas/ContentRefReusableContent"},{"$ref":"#/components/schemas/ContentRefTag"},{"$ref":"#/components/schemas/ContentRefOpenAPI"}]},"ContentRefFile":{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"file":{"type":"string"},"space":{"description":"ID of the space the file is in. The file is considered as in the current space if none is provided.","type":"string"}},"required":["kind","file"]},"ContentRefURL":{"type":"object","properties":{"kind":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["kind","url"]},"ContentRefPage":{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"page":{"type":"string"},"space":{"description":"ID of the space the page is in. The page is considered as in the current space if none is provided.","type":"string"}},"required":["kind","page"]},"ContentRefAnchor":{"type":"object","properties":{"kind":{"type":"string","enum":["anchor"]},"anchor":{"type":"string"},"space":{"description":"ID of the space the page is in. The page is considered as in the current space if none is provided.","type":"string"},"page":{"description":"ID of the page the anchor is in. The anchor is considered as in the current page if none is provided.","type":"string"}},"required":["kind","anchor"]},"ContentRefUser":{"type":"object","properties":{"kind":{"type":"string","enum":["user"]},"user":{"type":"string"}},"required":["kind","user"]},"ContentRefCollection":{"type":"object","properties":{"kind":{"type":"string","enum":["collection"]},"collection":{"type":"string"}},"required":["kind","collection"]},"ContentRefSpace":{"type":"object","properties":{"kind":{"type":"string","enum":["space"]},"space":{"type":"string"}},"required":["kind","space"]},"ContentRefReusableContent":{"type":"object","properties":{"kind":{"type":"string","enum":["reusable-content"]},"reusableContent":{"type":"string"},"space":{"type":"string","description":"The space in which the reusable content is defined. If undefined, the reusable content is assumed to be in the same space as the content reference."}},"required":["kind","reusableContent"]},"ContentRefTag":{"type":"object","properties":{"kind":{"type":"string","enum":["tag"]},"tag":{"type":"string","description":"The slug of the tag, also used as the ID, and references the tags defined on a revision."},"space":{"type":"string","description":"The space in which the tag is defined. If undefined, the tag is assumed to be in the same space as the content reference."}},"required":["kind","tag"]},"ContentRefOpenAPI":{"type":"object","properties":{"kind":{"type":"string","enum":["openapi"]},"spec":{"type":"string","description":"Slug of the OpenAPI specification"}},"required":["kind","spec"]},"SiteInsightsLinkPosition":{"type":"string","enum":["announcement","header","footer","sidebar","content"]},"SiteInsightsEventAPIClientOpen":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["api_client_open"]},"operation":{"$ref":"#/components/schemas/OpenAPIOperationPointer"}},"required":["type","operation"]}]},"OpenAPIOperationPointer":{"type":"object","description":"Pointer to an operation in the OpenAPI spec.","properties":{"path":{"type":"string","description":"Path of the operation in the OpenAPI spec."},"method":{"type":"string","description":"HTTP method of the operation in the OpenAPI spec."}},"required":["path","method"]},"SiteInsightsEventAPIClientRequest":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["api_client_request"]},"operation":{"$ref":"#/components/schemas/OpenAPIOperationPointer"}},"required":["type","operation"]}]},"SiteInsightsEventTrademarkClick":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["trademark_click"]},"placement":{"$ref":"#/components/schemas/SiteInsightsTrademarkPlacement"}},"required":["type","placement"]}]},"SiteInsightsTrademarkPlacement":{"type":"string","enum":["sidebar","ad","footer","pdf","embed"]},"SiteInsightsEventAdClick":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["ad_click"]},"ad":{"$ref":"#/components/schemas/SiteInsightsAd"}},"required":["type","ad"]}]},"SiteInsightsAd":{"type":"object","properties":{"domain":{"type":"string"},"zoneId":{"type":"string"},"placement":{"$ref":"#/components/schemas/SiteInsightsAdPlacement"}},"required":["domain","zoneId","placement"]},"SiteInsightsAdPlacement":{"type":"string","enum":["aside"]},"SiteInsightsEventAdDisplay":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["ad_display"]},"ad":{"$ref":"#/components/schemas/SiteInsightsAd"}},"required":["type","ad"]}]},"SiteInsightsEventLLMSRequest":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["llms_request"]},"llmsVariant":{"$ref":"#/components/schemas/SiteInsightsLLMSVariant"}},"required":["type","llmsVariant"]}]},"SiteInsightsLLMSVariant":{"type":"string","enum":["standard","full"]},"SiteInsightsEventMCPRequest":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["mcp_request"]}},"required":["type"]}]},"SiteInsightsEventRSSRequest":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsEventBase"},{"type":"object","properties":{"type":{"type":"string","enum":["rss_request"]}},"required":["type"]}]}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/insights/events":{"post":{"operationId":"trackEventsInSiteById","summary":"Track site events","tags":["site-insights"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"}],"responses":{"204":{"description":"Events have been tracked."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsEvent"}}},"required":["events"]}}}}}}}}
```

## POST /orgs/{organizationId}/sites/{siteId}/insights/events/aggregate

> Query site events

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-insights","description":"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.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"SiteInsightsQueryEventsAggregation":{"type":"object","required":["range"],"properties":{"select":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsQueryEventsColumn"}},"where":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsQueryEventsFilter"}},"groupBy":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsQueryEventsColumn"}},"order":{"type":"object","required":["by","direction"],"properties":{"by":{"$ref":"#/components/schemas/SiteInsightsQueryEventsColumn"},"direction":{"type":"string","enum":["asc","desc"]}}},"range":{"$ref":"#/components/schemas/SiteInsightsQueryRange"},"limit":{"type":"integer","default":1000,"minimum":1,"maximum":1000}}},"SiteInsightsQueryEventsColumn":{"oneOf":[{"$ref":"#/components/schemas/SiteInsightsQueryDateTimeColumn"},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["url"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventType"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventsCount"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["sessionsCount"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorsCount"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["siteSection"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["siteSpace"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["siteShareKey"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["displayContext"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["page"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorGeoCountry"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorGeoPoint"]},"precision":{"type":"integer","minimum":0,"maximum":15}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorDevice"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorBrowser"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorOS"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorBot"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorLanguage"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventLinkTargetValue"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventLinkTargetKind"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventLinkTargetDomain"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventLinkPosition"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventAPIOperationPath"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventAPIOperationMethod"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventLLMSVariant"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventSearchQuery"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventSearchResultRecordId"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventPageFeedbackRating"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventPageFeedbackComment"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventAskResponseRating"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["pageFeedbackRating"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["askResponseRating"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["referrer"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["referrerDomain"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["utmSource"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["utmMedium"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["utmCampaign"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["utmTerm"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["utmContent"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["visitorClaimProperty"]}}},{"type":"object","required":["column","claim"],"properties":{"column":{"type":"string","enum":["visitorClaim"]},"claim":{"type":"string"}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventAdDomain"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventAdPlacement"]}}},{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["eventTrademarkPlacement"]}}}]},"SiteInsightsQueryDateTimeColumn":{"type":"object","required":["column"],"properties":{"column":{"type":"string","enum":["datetime"]},"interval":{"type":"string","enum":["hour","day","week","month"]}}},"SiteInsightsQueryEventsFilter":{"allOf":[{"$ref":"#/components/schemas/SiteInsightsQueryEventsValues"},{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/SiteInsightsQueryOperator"}}}]},"SiteInsightsQueryEventsValues":{"oneOf":[{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["datetime"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/Timestamp"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["url"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/URL"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventsCount"]},"values":{"type":"array","items":{"type":"number"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["sessionsCount"]},"values":{"type":"array","items":{"type":"number"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorsCount"]},"values":{"type":"array","items":{"type":"number"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventType"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsEventType"}}}},{"type":"object","required":["column","claim","values"],"properties":{"column":{"type":"string","enum":["visitorClaim"]},"claim":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorClaimProperty"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorBrowser"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsVisitorBrowser"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorDevice"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsVisitorDevice"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorOS"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsVisitorOS"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorBot"]},"values":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SiteInsightsVisitorBot"},{"type":"string","enum":[""]}]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventLinkTargetValue"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/ContentRef"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventLinkTargetKind"]},"values":{"type":"array","items":{"type":"string","enum":["url","page","file","anchor","space","collection","user","reusable-content"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventLinkPosition"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsLinkPosition"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["siteSection"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventLLMSVariant"]},"values":{"type":"array","items":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SiteInsightsLLMSVariant"}]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["siteSpace"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["siteShareKey"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["displayContext"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsDisplayContext"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["page"]},"values":{"type":"array","items":{"oneOf":[{"type":"null"},{"type":"object","required":["page","space"],"properties":{"page":{"type":["string","null"]},"space":{"type":"string"}}}]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorGeoCountry"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorGeoPoint"]},"values":{"type":"array","items":{"type":["object","null"],"required":["latitude","longitude","h3"],"properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"h3":{"type":"string"}}}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["visitorLanguage"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventLinkTargetDomain"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventAPIOperationPath"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventAPIOperationMethod"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventSearchQuery"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventSearchResultRecordId"]},"values":{"type":"array","items":{"type":["string","null"]}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["pageFeedbackRating"]},"values":{"type":"array","items":{"type":"object","required":["ok","good","bad"],"properties":{"ok":{"type":"number"},"good":{"type":"number"},"bad":{"type":"number"}}}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["askResponseRating"]},"values":{"type":"array","items":{"type":"object","required":["positive","negative"],"properties":{"positive":{"type":"number"},"negative":{"type":"number"}}}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventPageFeedbackRating"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/PageFeedbackRating"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventAskResponseRating"]},"values":{"type":"array","items":{"type":"integer"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventPageFeedbackComment"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["referrer"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["referrerDomain"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["utmSource"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["utmMedium"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["utmCampaign"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["utmTerm"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["utmContent"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventAdDomain"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventAdPlacement"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsAdPlacement"}}}},{"type":"object","required":["column","values"],"properties":{"column":{"type":"string","enum":["eventTrademarkPlacement"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsTrademarkPlacement"}}}}]},"Timestamp":{"type":"string","format":"date-time"},"URL":{"type":"string","format":"uri","maxLength":2048},"SiteInsightsEventType":{"type":"string","enum":["page_view","page_markdown_request","search_open","search_type_query","search_open_result","page_post_feedback","page_post_feedback_comment","ask_question","ask_view","ask_rate_response","link_click","api_client_open","api_client_request","ad_click","ad_display","trademark_click","llms_request","mcp_request","rss_request"]},"SiteInsightsVisitorBrowser":{"type":"string","enum":["chrome","firefox","safari","edge","ie","opera","unknown"]},"SiteInsightsVisitorDevice":{"type":"string","enum":["desktop","tablet","mobile","unknown"]},"SiteInsightsVisitorOS":{"type":"string","enum":["windows","macos","linux","android","ios","unknown"]},"SiteInsightsVisitorBot":{"type":["string","null"],"enum":[null,"unknown","googlebot","bingbot","duckduckbot","facebookbot","applebot","chatgpt","openai","claude","anthropic","gemini","perplexity","cohere","mistral","deepseek","meta","bytespider","ccbot","amazonbot","youbot","cursor","vscode","claude-code","codex","opencode"]},"ContentRef":{"description":"A relative reference to content in GitBook.","oneOf":[{"$ref":"#/components/schemas/ContentRefFile"},{"$ref":"#/components/schemas/ContentRefURL"},{"$ref":"#/components/schemas/ContentRefPage"},{"$ref":"#/components/schemas/ContentRefAnchor"},{"$ref":"#/components/schemas/ContentRefUser"},{"$ref":"#/components/schemas/ContentRefCollection"},{"$ref":"#/components/schemas/ContentRefSpace"},{"$ref":"#/components/schemas/ContentRefReusableContent"},{"$ref":"#/components/schemas/ContentRefTag"},{"$ref":"#/components/schemas/ContentRefOpenAPI"}]},"ContentRefFile":{"type":"object","properties":{"kind":{"type":"string","enum":["file"]},"file":{"type":"string"},"space":{"description":"ID of the space the file is in. The file is considered as in the current space if none is provided.","type":"string"}},"required":["kind","file"]},"ContentRefURL":{"type":"object","properties":{"kind":{"type":"string","enum":["url"]},"url":{"type":"string"}},"required":["kind","url"]},"ContentRefPage":{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"page":{"type":"string"},"space":{"description":"ID of the space the page is in. The page is considered as in the current space if none is provided.","type":"string"}},"required":["kind","page"]},"ContentRefAnchor":{"type":"object","properties":{"kind":{"type":"string","enum":["anchor"]},"anchor":{"type":"string"},"space":{"description":"ID of the space the page is in. The page is considered as in the current space if none is provided.","type":"string"},"page":{"description":"ID of the page the anchor is in. The anchor is considered as in the current page if none is provided.","type":"string"}},"required":["kind","anchor"]},"ContentRefUser":{"type":"object","properties":{"kind":{"type":"string","enum":["user"]},"user":{"type":"string"}},"required":["kind","user"]},"ContentRefCollection":{"type":"object","properties":{"kind":{"type":"string","enum":["collection"]},"collection":{"type":"string"}},"required":["kind","collection"]},"ContentRefSpace":{"type":"object","properties":{"kind":{"type":"string","enum":["space"]},"space":{"type":"string"}},"required":["kind","space"]},"ContentRefReusableContent":{"type":"object","properties":{"kind":{"type":"string","enum":["reusable-content"]},"reusableContent":{"type":"string"},"space":{"type":"string","description":"The space in which the reusable content is defined. If undefined, the reusable content is assumed to be in the same space as the content reference."}},"required":["kind","reusableContent"]},"ContentRefTag":{"type":"object","properties":{"kind":{"type":"string","enum":["tag"]},"tag":{"type":"string","description":"The slug of the tag, also used as the ID, and references the tags defined on a revision."},"space":{"type":"string","description":"The space in which the tag is defined. If undefined, the tag is assumed to be in the same space as the content reference."}},"required":["kind","tag"]},"ContentRefOpenAPI":{"type":"object","properties":{"kind":{"type":"string","enum":["openapi"]},"spec":{"type":"string","description":"Slug of the OpenAPI specification"}},"required":["kind","spec"]},"SiteInsightsLinkPosition":{"type":"string","enum":["announcement","header","footer","sidebar","content"]},"SiteInsightsLLMSVariant":{"type":"string","enum":["standard","full"]},"SiteInsightsDisplayContext":{"type":"string","description":"Context in which the event was recorded.","enum":["site","server","embed","mcp"]},"PageFeedbackRating":{"type":"string","enum":["bad","ok","good"]},"SiteInsightsAdPlacement":{"type":"string","enum":["aside"]},"SiteInsightsTrademarkPlacement":{"type":"string","enum":["sidebar","ad","footer","pdf","embed"]},"SiteInsightsQueryOperator":{"type":"string","enum":["in","notIn","greaterThan","greaterThanOrEqual","lessThan","lessThanOrEqual"]},"SiteInsightsQueryRange":{"oneOf":[{"$ref":"#/components/schemas/SiteInsightsQueryRangePreset"},{"$ref":"#/components/schemas/SiteInsightsQueryRangeCustom"}]},"SiteInsightsQueryRangePreset":{"type":"string","enum":["lastYear","last3Months","last30Days","last7Days","last24Hours"]},"SiteInsightsQueryRangeCustom":{"type":"object","properties":{"from":{"$ref":"#/components/schemas/Timestamp"},"to":{"$ref":"#/components/schemas/Timestamp"}},"required":["from","to"]},"SiteInsightsQueryEventsAggregationResult":{"type":"object","required":["columns"],"properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsQueryEventsValues"}}}}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate":{"post":{"operationId":"aggregateSiteEvents","summary":"Query site events","tags":["site-insights"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteInsightsQueryEventsAggregation"}}}},"responses":{"200":{"description":"Aggregated events in the site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteInsightsQueryEventsAggregationResult"}}}}}}}}}
```

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

> List a site visitor segments

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"site-insights","description":"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.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]},{"user-internal":[]},{"user-staff":[]},{"user-internal-or-staff":[]},{"integration":[]},{"integration-installation":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"},"user-internal":{"type":"http","scheme":"bearer"},"user-staff":{"type":"http","scheme":"bearer"},"user-internal-or-staff":{"type":"http","scheme":"bearer"},"integration":{"type":"http","scheme":"bearer"},"integration-installation":{"type":"http","scheme":"bearer"}},"parameters":{"organizationId":{"name":"organizationId","in":"path","required":true,"description":"The unique id of the organization","schema":{"$ref":"#/components/schemas/EntityId"}},"siteId":{"name":"siteId","in":"path","required":true,"description":"The unique id of the site","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"SiteInsightsVisitorSegment":{"type":"object","description":"A segment of visitors with the same characteristics.","properties":{"title":{"type":"string","description":"The title of the visitor profile."},"claims":{"$ref":"#/components/schemas/PlainObject"},"events":{"type":"number","description":"The number of events for this visitor profile."},"visitors":{"type":"number","description":"The number of visitors for this visitor profile."},"sessions":{"type":"number","description":"The number of sessions for this visitor profile."}},"required":["title","claims","events","visitors","sessions"]},"PlainObject":{"properties":{},"additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/PlainObject"},{"type":"string"},{"type":"boolean"},{"type":"number"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"boolean"},{"type":"number"},{"$ref":"#/components/schemas/PlainObject"}]}}]}}}},"paths":{"/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments":{"get":{"operationId":"listSiteVisitorSegments","summary":"List a site visitor segments","tags":["site-insights"],"parameters":[{"$ref":"#/components/parameters/organizationId"},{"$ref":"#/components/parameters/siteId"}],"responses":{"200":{"description":"List of visitor segments in the site.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteInsightsVisitorSegment"}}}}]}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/site-insights.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.