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

# List countries of users for a brand report

> Per-country breakdown of human visits measured by the User Analytics snippet, busiest country first. Countries are lowercase ISO 3166-1 alpha-2 codes (`uk` for the United Kingdom); `zz` is the visits whose country is unknown. The codes returned here are what `country` accepts on the stats and pages endpoints. Without `source` the counts cover the AI assistants only, as in the app.



## OpenAPI

````yaml https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/user-analytics/countries
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/countries:
    get:
      tags:
        - Brand Reports
      summary: List countries of users for a brand report
      description: >-
        Per-country breakdown of human visits measured by the User Analytics
        snippet, busiest country first. Countries are lowercase ISO 3166-1
        alpha-2 codes (`uk` for the United Kingdom); `zz` is the visits whose
        country is unknown. The codes returned here are what `country` accepts
        on the stats and pages endpoints. Without `source` the counts cover the
        AI assistants only, as in the app.
      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:
            type: integer
            description: >-
              Optional. Zero-based offset for pagination; must be a multiple of
              `limit`. Defaults to 0.
          required: false
          description: >-
            Optional. Zero-based offset for pagination; must be a multiple of
            `limit`. Defaults to 0.
          name: offset
          in: query
        - schema:
            type: integer
            description: >-
              Optional. Maximum number of items to return, up to 100. Defaults
              to 25.
          required: false
          description: >-
            Optional. Maximum number of items to return, up to 100. Defaults to
            25.
          name: limit
          in: query
      responses:
        '200':
          description: A page of countries for the brand report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiUserAnalyticsCountriesList'
        '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:
    PublicApiUserAnalyticsCountriesList:
      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).
        items:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiUserAnalyticsCountry'
          description: Visits per country in the window, highest first.
        paging:
          $ref: '#/components/schemas/PublicApiOffsetPagingWithTotal'
      required:
        - availability
        - startDate
        - endDate
        - domains
        - items
        - paging
      example:
        availability: connected_with_data
        startDate: '2026-09-23'
        endDate: '2026-10-06'
        domains:
          - adidas.com
          - blog.adidas.com
        items:
          - country: us
            visits: 2210
          - country: uk
            visits: 684
          - country: de
            visits: 512
          - country: zz
            visits: 37
        paging:
          limit: 25
          offset: 0
          totalCount: 18
          hasMore: false
    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
    PublicApiUserAnalyticsCountry:
      type: object
      properties:
        country:
          type: string
          description: >-
            Lowercase ISO 3166-1 alpha-2 code, with `uk` in place of `gb`. `zz`
            is the visits whose country is unknown.
          example: us
        visits:
          type: integer
          minimum: 0
      required:
        - country
        - visits
      example:
        country: us
        visits: 2210
    PublicApiOffsetPagingWithTotal:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
        offset:
          type: integer
          minimum: 0
        totalCount:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
          description: True when a further page exists at `offset + limit`.
      required:
        - limit
        - offset
        - totalCount
        - hasMore
      example:
        limit: 25
        offset: 0
        hasMore: true
        totalCount: 137
  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.