> ## Documentation Index > Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Query analytics totals and breakdowns > Returns aggregate engagement totals — page views, distinct visitors, visits, bounces, and total time in seconds — for a date range, optionally broken down by one dimension. Use it to answer "how much traffic did the site get" and "what are the top pages/referrers/countries" style questions; use the timeseries endpoint when you need values over time instead. `startAt` and `endAt` are Unix epoch milliseconds; optional filter parameters (path, referrer, country, event, UTM fields, ...) narrow the data. Without `dimension` the response carries the totals alone. With `dimension` (e.g. `path` for top pages, `referrer` for top referrers, `country` for top countries) the response also carries `rows`: up to `limit` (default 25, max 1000) values of that dimension ranked by page views, each with its own engagement totals. Requires a plan that includes analytics (403 otherwise); all-zero totals until the website is published and has traffic. ## OpenAPI ````yaml /api-reference/openapi.json get /websites/{websiteId}/analytics/query openapi: 3.1.0 info: title: Cactal API version: 1.0.0 description: >- The Cactal public API. Create, edit, publish, and operate websites programmatically. Authenticate every request with an API key sent as `Authorization: Bearer `. servers: - url: https://api.cactal.ai/v1 security: - apiKey: [] tags: - name: Documentation description: >- Search and read the Cactal product documentation for concepts, guides, agent workflows, platform behavior, and API operations. - name: Feedback description: >- Submit free-form product feedback from users and agents to the Cactal feedback inbox. - name: Websites description: >- Create and manage websites — the top-level resource that owns source code, content, assets, domains, and analytics. - name: Website editors description: >- Grant, list, and revoke website-scoped editor access, and invite collaborators to a single website by email. - name: API keys description: >- Create, scope, rotate, and revoke the API keys that authenticate programmatic and agent access. - name: Source code description: >- Read and edit the framework source files of a website draft. Mutations require an edit lease. - name: Publishing description: Validate, build, publish, and roll back website versions. - name: CMS collections description: >- Define the content model: collections of structured content owned by a website. - name: CMS fields description: Manage the typed fields that make up a collection schema. - name: CMS items description: >- Create, query, publish, and organize the content entries inside a collection. - name: Domains description: >- Manage platform subdomains and custom domains, including DNS verification and the primary domain. - name: Assets description: Upload and manage website files and images served from the Cactal CDN. - name: Media generation description: >- Generate reference-guided website images that are stored as ordinary Cactal CDN assets. - name: Project Context description: >- Upload private durable reference material that the website agent can search, read, and inspect. - name: Analytics description: >- Read first-party traffic analytics for a website and export datasets as CSV. - name: Organizations description: Manage organizations, members, and organization-wide invitations. - name: Audit log description: >- Read the immutable record of actions performed in an organization by users and API keys. - name: Billing description: >- Read billing state and manage plans, site capacity, and prepaid usage balance. Every billing operation requires the organization owner role, which API keys cannot hold — today these operations are performed from the dashboard, return 403 for API-key callers, and are hidden from MCP tool lists. paths: /websites/{websiteId}/analytics/query: get: tags: - Analytics summary: Query analytics totals and breakdowns description: >- Returns aggregate engagement totals — page views, distinct visitors, visits, bounces, and total time in seconds — for a date range, optionally broken down by one dimension. Use it to answer "how much traffic did the site get" and "what are the top pages/referrers/countries" style questions; use the timeseries endpoint when you need values over time instead. `startAt` and `endAt` are Unix epoch milliseconds; optional filter parameters (path, referrer, country, event, UTM fields, ...) narrow the data. Without `dimension` the response carries the totals alone. With `dimension` (e.g. `path` for top pages, `referrer` for top referrers, `country` for top countries) the response also carries `rows`: up to `limit` (default 25, max 1000) values of that dimension ranked by page views, each with its own engagement totals. Requires a plan that includes analytics (403 otherwise); all-zero totals until the website is published and has traffic. operationId: websiteAnalytics.query.get parameters: - name: websiteId in: path required: true schema: type: string minLength: 1 - name: startAt in: query required: true schema: type: integer minimum: 0 maximum: 9007199254740991 - name: endAt in: query required: true schema: type: integer minimum: 0 maximum: 9007199254740991 - name: path in: query required: false schema: type: string - name: referrer in: query required: false schema: type: string - name: title in: query required: false schema: type: string - name: query in: query required: false schema: type: string - name: browser in: query required: false schema: type: string - name: os in: query required: false schema: type: string - name: device in: query required: false schema: type: string - name: country in: query required: false schema: type: string - name: region in: query required: false schema: type: string - name: city in: query required: false schema: type: string - name: language in: query required: false schema: type: string - name: hostname in: query required: false schema: type: string - name: tag in: query required: false schema: type: string - name: event in: query required: false schema: type: string - name: distinctId in: query required: false schema: type: string - name: utmSource in: query required: false schema: type: string - name: utmMedium in: query required: false schema: type: string - name: utmCampaign in: query required: false schema: type: string - name: utmContent in: query required: false schema: type: string - name: utmTerm in: query required: false schema: type: string - name: segment in: query required: false schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - name: cohort in: query required: false schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - name: dimension in: query required: false schema: description: >- Break the range down by this dimension, e.g. `path` for top pages, `referrer` for top referrers, `country` for top countries. Omit for totals only. type: string enum: - path - entry - exit - title - query - referrer - channel - domain - country - region - city - browser - os - device - language - screen - event - hostname - tag - distinctId - name: limit in: query required: false schema: default: 25 description: >- Maximum number of dimension rows to return (default 25, max 1000). Only used when `dimension` is set. type: integer minimum: 1 maximum: 1000 responses: '200': description: >- Engagement totals for the range, plus ranked `rows` when a `dimension` was requested. content: application/json: schema: type: object properties: pageviews: type: number description: Total page views. visitors: type: number description: Distinct visitors. visits: type: number description: Visits (sessions). bounces: type: number description: Single-page visits. totaltime: type: number description: Total time spent in seconds, summed across visits. comparison: description: >- Totals for the comparison period, present when the provider computes one. type: object properties: pageviews: type: number description: Total page views. visitors: type: number description: Distinct visitors. visits: type: number description: Visits (sessions). bounces: type: number description: Single-page visits. totaltime: type: number description: Total time spent in seconds, summed across visits. required: - pageviews - visitors - visits - bounces - totaltime additionalProperties: false rows: description: >- Values of the requested `dimension` ranked by page views, each with its own engagement totals. Present only when `dimension` is set. type: array items: type: object properties: name: type: string description: >- Dimension value, e.g. the URL path, referrer domain, or country code. pageviews: type: number description: Total page views. visitors: type: number description: Distinct visitors. visits: type: number description: Visits (sessions). bounces: type: number description: Single-page visits. totaltime: type: number description: Total time spent in seconds, summed across visits. required: - name - pageviews - visitors - visits - bounces - totaltime additionalProperties: false required: - pageviews - visitors - visits - bounces - totaltime additionalProperties: false '400': description: >- Validation failed. The response `message` names the first invalid field. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '401': description: Missing, invalid, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '403': description: The authenticated principal lacks the required capability. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '404': description: >- The resource does not exist or is outside the principal’s access scope. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '429': description: >- Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ServiceError' components: schemas: ServiceError: type: object required: - kind - message description: >- Canonical error body returned by every non-2xx response. Extra fields carry error-specific details. properties: kind: type: string enum: - validation - unauthorized - forbidden - not_found - conflict - rate_limited - internal description: Stable, machine-readable error category. message: type: string description: Human-readable explanation of the failure. suggestion: type: string description: >- What to do next when the failure has a known fix; may name the exact operation to call. validValues: type: array items: type: string description: The acceptable values for the failing field, when the set is closed. additionalProperties: true securitySchemes: apiKey: type: http scheme: bearer description: >- Cactal API key. Create one in the dashboard or via `POST /apiKeys`. The plaintext key is shown once at creation. ````