> ## 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.

# Get an analytics time series

> Returns one traffic time series bucketed by `unit` (`year`, `month`, `day`, `hour`, or `minute`). `series` selects which: `pageviews` returns parallel `pageviews` and `sessions` arrays with one point per time bucket (and accepts `compare` — `prev` or `yoy` — to request comparison data for the previous period or year), while `events` returns tracked custom-event counts as one `events` point per event name per time bucket. Only the requested series' fields are present in the response. `startAt` and `endAt` are Unix epoch milliseconds; `timezone` is an IANA name (e.g. `America/New_York`) that controls bucket boundaries; optional filter parameters narrow the data. The series is capped to the most recent `maxPoints` time buckets (default 30, max 500); a `truncated` field reports when the cap was applied. Requires a plan that includes analytics (403 otherwise); empty until the website is published and has traffic.



## OpenAPI

````yaml /api-reference/openapi.json get /websites/{websiteId}/analytics/timeseries
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 <key>`.
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/timeseries:
    get:
      tags:
        - Analytics
      summary: Get an analytics time series
      description: >-
        Returns one traffic time series bucketed by `unit` (`year`, `month`,
        `day`, `hour`, or `minute`). `series` selects which: `pageviews` returns
        parallel `pageviews` and `sessions` arrays with one point per time
        bucket (and accepts `compare` — `prev` or `yoy` — to request comparison
        data for the previous period or year), while `events` returns tracked
        custom-event counts as one `events` point per event name per time
        bucket. Only the requested series' fields are present in the response.
        `startAt` and `endAt` are Unix epoch milliseconds; `timezone` is an IANA
        name (e.g. `America/New_York`) that controls bucket boundaries; optional
        filter parameters narrow the data. The series is capped to the most
        recent `maxPoints` time buckets (default 30, max 500); a `truncated`
        field reports when the cap was applied. Requires a plan that includes
        analytics (403 otherwise); empty until the website is published and has
        traffic.
      operationId: websiteAnalytics.timeseries.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: unit
          in: query
          required: true
          schema:
            type: string
            enum:
              - year
              - month
              - day
              - hour
              - minute
        - name: timezone
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: maxPoints
          in: query
          required: false
          schema:
            default: 30
            type: integer
            minimum: 1
            maximum: 500
        - name: series
          in: query
          required: true
          schema:
            type: string
            enum:
              - pageviews
              - events
            description: >-
              Which time series to return: `pageviews` for page views and
              sessions per bucket, `events` for tracked custom-event counts per
              event name per bucket.
        - name: compare
          in: query
          required: false
          schema:
            description: >-
              Request comparison data alongside the primary series: `prev` for
              the previous period, `yoy` for the same range one year earlier.
              Only valid when `series` is `pageviews`.
            type: string
            enum:
              - prev
              - yoy
      responses:
        '200':
          description: >-
            The requested time series: `pageviews` and `sessions` per bucket, or
            `events` per event name per bucket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageviews:
                    description: >-
                      Page views per time bucket. Present only when `series` is
                      `pageviews`.
                    type: array
                    items:
                      type: object
                      properties:
                        x:
                          type: string
                          description: Start of the time bucket.
                        'y':
                          type: number
                          description: Count in the bucket.
                      required:
                        - x
                        - 'y'
                      additionalProperties: false
                  sessions:
                    description: >-
                      Distinct sessions per time bucket. Present only when
                      `series` is `pageviews`.
                    type: array
                    items:
                      type: object
                      properties:
                        x:
                          type: string
                          description: Start of the time bucket.
                        'y':
                          type: number
                          description: Count in the bucket.
                      required:
                        - x
                        - 'y'
                      additionalProperties: false
                  events:
                    description: >-
                      One point per event name per time bucket. Present only
                      when `series` is `events`.
                    type: array
                    items:
                      type: object
                      properties:
                        x:
                          type: string
                          description: Event name.
                        t:
                          type: string
                          description: Start of the time bucket.
                        'y':
                          type: number
                          description: Number of events in the bucket.
                      required:
                        - x
                        - t
                        - 'y'
                      additionalProperties: false
                  truncated:
                    description: >-
                      Present only when the series exceeded `maxPoints` and was
                      capped to the most recent time buckets.
                    type: object
                    properties:
                      shown:
                        type: integer
                        description: Time buckets returned.
                      total:
                        type: integer
                        description: Time buckets the range produced.
                      hint:
                        type: string
                        description: How to retrieve the rest.
                    required:
                      - shown
                      - total
                      - hint
                    additionalProperties: false
                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.

````