> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otterly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get user traffic overview for a brand report

> Overview of human visitors to the brand report's own domains, measured by the User Analytics snippet: total visits, unique visitors, distinct pages visited, the top source, per-source totals and a daily trend per source. A source is the AI assistant that sent the visitor (`openai`, `perplexity`, `google`, …), or `other_external`, `direct_none`, `internal_self`. Without `source` the totals cover the AI assistants only, as in the app. A named source replaces that set: `source=direct_none` is direct visits alone; repeat `source` to mix. Check `availability` before rendering — `not_connected` means no User Analytics site is set up for this report and the metrics are `null`, not zero.



## OpenAPI

````yaml https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/user-analytics/stats
openapi: 3.0.0
info:
  title: Otterly Public API
  version: 1.0.0
servers:
  - url: https://data.otterly.ai
security: []
tags:
  - name: Engines
  - name: Workspaces
  - name: Tags
  - name: Prompts
  - name: Brand Reports
  - name: Competitors
  - name: Audits
  - name: Accounts
paths:
  /v1/reports/brand/{reportId}/user-analytics/stats:
    get:
      tags:
        - Brand Reports
      summary: Get user traffic overview for a brand report
      description: >-
        Overview of human visitors to the brand report's own domains, measured
        by the User Analytics snippet: total visits, unique visitors, distinct
        pages visited, the top source, per-source totals and a daily trend per
        source. A source is the AI assistant that sent the visitor (`openai`,
        `perplexity`, `google`, …), or `other_external`, `direct_none`,
        `internal_self`. Without `source` the totals cover the AI assistants
        only, as in the app. A named source replaces that set:
        `source=direct_none` is direct visits alone; repeat `source` to mix.
        Check `availability` before rendering — `not_connected` means no User
        Analytics site is set up for this report and the metrics are `null`, not
        zero.
      parameters:
        - schema:
            type: string
            minLength: 1
            example: 01HX7K2YV9D3M8N0G6Q5R4S3T2
            description: Brand report identifier.
          required: true
          description: Brand report identifier.
          name: reportId
          in: path
        - schema:
            type: string
            description: >-
              Optional. Start of the window (inclusive), `YYYY-MM-DD`. Omit it
              to get the 13 days before `endDate`; omit both dates for the last
              14 days (UTC), matching the dashboard.
            example: '2026-08-07'
          required: false
          description: >-
            Optional. Start of the window (inclusive), `YYYY-MM-DD`. Omit it to
            get the 13 days before `endDate`; omit both dates for the last 14
            days (UTC), matching the dashboard.
          name: startDate
          in: query
        - schema:
            type: string
            description: >-
              Optional. End of the window (inclusive), `YYYY-MM-DD`. Defaults to
              today (UTC).
            example: '2026-08-20'
          required: false
          description: >-
            Optional. End of the window (inclusive), `YYYY-MM-DD`. Defaults to
            today (UTC).
          name: endDate
          in: query
        - schema:
            anyOf:
              - type: string
                minLength: 1
                maxLength: 50
              - type: array
                items:
                  type: string
                  minLength: 1
                  maxLength: 50
                minItems: 1
            description: >-
              Optional. Keep only visits from these sources: an AI service
              (`openai`, `perplexity`, `google`, `microsoft`, `anthropic`, …),
              `other_external` (another website), `direct_none` (no referrer) or
              `internal_self` (another page of the site). Repeat the param for
              several, up to 50. Omitted, it means the AI assistants only, as in
              the app. Naming sources replaces that set: `source=direct_none`
              returns direct visits alone; repeat the param to mix AI and non-AI
              sources.
          required: false
          description: >-
            Optional. Keep only visits from these sources: an AI service
            (`openai`, `perplexity`, `google`, `microsoft`, `anthropic`, …),
            `other_external` (another website), `direct_none` (no referrer) or
            `internal_self` (another page of the site). Repeat the param for
            several, up to 50. Omitted, it means the AI assistants only, as in
            the app. Naming sources replaces that set: `source=direct_none`
            returns direct visits alone; repeat the param to mix AI and non-AI
            sources.
          name: source
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
                minItems: 1
            description: >-
              Optional. Keep only visits from these countries: ISO 3166-1
              alpha-2 codes as the countries endpoint lists them (`us`, `de`;
              `uk` for the United Kingdom; `zz` for the visits whose country is
              unknown). Repeat the param for several. Omit for all countries.
          required: false
          description: >-
            Optional. Keep only visits from these countries: ISO 3166-1 alpha-2
            codes as the countries endpoint lists them (`us`, `de`; `uk` for the
            United Kingdom; `zz` for the visits whose country is unknown).
            Repeat the param for several. Omit for all countries.
          name: country
          in: query
      responses:
        '200':
          description: User traffic overview for the brand report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiUserAnalyticsStats'
        '400':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiValidationErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        '404':
          description: Report not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    PublicApiUserAnalyticsStats:
      type: object
      properties:
        availability:
          type: string
          enum:
            - not_connected
            - connected_no_data
            - connected_with_data
          description: >-
            Whether these numbers can be trusted. `not_connected` means no logs
            connector is active for this report — metrics are `null`, NOT zero,
            because nothing is being measured. `connected_no_data` means a
            connector is active but matched no visits in this window, so the
            zeros are real. `connected_with_data` means the payload is
            populated.
          example: connected_with_data
        startDate:
          type: string
          description: Start of the resolved window (inclusive), `YYYY-MM-DD`.
        endDate:
          type: string
          description: End of the resolved window (inclusive), `YYYY-MM-DD`.
        domains:
          type: array
          items:
            type: string
          description: >-
            The report's own domains the query spanned, normalized (lowercased,
            `www.` and port stripped).
        totalVisits:
          type: integer
          nullable: true
          minimum: 0
          description: >-
            Page views in the window. `null` when `availability` is
            `not_connected`.
        pagesVisited:
          type: integer
          nullable: true
          minimum: 0
          description: >-
            Distinct pages visited in the window. `null` when `availability` is
            `not_connected`.
        uniqueVisitors:
          type: integer
          nullable: true
          minimum: 0
          description: >-
            Distinct visitors in the window (a visitor who returns on another
            day counts once; browsers that block storage are not counted).
            `null` when `availability` is `not_connected`, when the window
            starts more than about 13 months back (the raw events behind the
            count are kept 13 months), or when the count ran out of time. Narrow
            the window rather than retry.
        topSource:
          type: string
          nullable: true
          description: >-
            Source with the most visits in the window; `null` when there were
            none.
          example: openai
        sources:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                description: >-
                  Where the visitor came from: an AI service (`openai`,
                  `perplexity`, `google`, `microsoft`, `anthropic`, …),
                  `other_external` (another website), `direct_none` (no
                  referrer) or `internal_self` (another page of the same site).
                example: openai
              visits:
                type: integer
                minimum: 0
            required:
              - source
              - visits
          description: Window totals per source, highest first.
        trend:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiUserAnalyticsTrendPoint'
          description: Per-(day, source) visit series for the window.
      required:
        - availability
        - startDate
        - endDate
        - domains
        - totalVisits
        - pagesVisited
        - uniqueVisitors
        - topSource
        - sources
        - trend
      example:
        availability: connected_with_data
        startDate: '2026-09-23'
        endDate: '2026-10-06'
        domains:
          - adidas.com
          - blog.adidas.com
        totalVisits: 4570
        pagesVisited: 236
        uniqueVisitors: 3107
        topSource: openai
        sources:
          - source: openai
            visits: 2904
          - source: perplexity
            visits: 1011
          - source: google
            visits: 655
        trend:
          - dayId: '20261006'
            source: openai
            visitCount: 318
          - dayId: '20261006'
            source: perplexity
            visitCount: 97
    PublicApiValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
        target:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
              code:
                type: string
            required:
              - path
              - message
              - code
      required:
        - message
        - target
        - errors
      example:
        message: Validation failed
        target: query
        errors:
          - path: country
            message: Required
            code: invalid_type
    PublicApiErrorResponse:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - credits_limit
            - workspace_prompts_limit
            - prompts_limit
            - no_active_plan
          description: >-
            Machine-readable reason of a prompt-limit refusal (403):
            `credits_limit` (the team's credits can't cover the new prompts),
            `workspace_prompts_limit` (the workspace's prompts limit),
            `prompts_limit` (the team's prompts on prompts billing),
            `no_active_plan` (no paid plan or trial). Absent for other errors.
          example: credits_limit
      required:
        - message
      example:
        message: Report not found
    PublicApiUserAnalyticsTrendPoint:
      type: object
      properties:
        dayId:
          type: string
          description: Day the visits fall on, `YYYYMMDD` (UTC).
          example: '20261006'
        source:
          type: string
          description: >-
            Where the visitor came from: an AI service (`openai`, `perplexity`,
            `google`, `microsoft`, `anthropic`, …), `other_external` (another
            website), `direct_none` (no referrer) or `internal_self` (another
            page of the same site).
          example: openai
        visitCount:
          type: integer
          minimum: 0
      required:
        - dayId
        - source
        - visitCount
      example:
        dayId: '20261006'
        source: openai
        visitCount: 318
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Provide your API key as a Bearer token: `Authorization: Bearer
        YOUR_API_KEY`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.