# 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","anthropic","gemini","perplexity","cohere","mistral","deepseek","meta","bytespider","ccbot","amazonbot","youbot","cursor","vscode","claude-code"]},"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"}}}}]}}}}}}}}}
```