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

# Click report — scans reported apart from clicks

> Requires a token with the `analytics:read` permission.



## OpenAPI

````yaml /openapi.json get /api/v1/analytics/report
openapi: 3.0.0
info:
  description: >-
    Every request carries `Authorization: Bearer utmk_…`. The token fixes the
    workspace; no request names one. Every operation declares `x-permission`,
    the token permission it requires.
  title: UTM Builder API
  version: '1'
servers:
  - url: https://app.utmkit.co
    variables: {}
security:
  - bearer: []
tags: []
paths:
  /api/v1/analytics/report:
    get:
      tags:
        - analytics
      summary: Click report — scans reported apart from clicks
      description: Requires a token with the `analytics:read` permission.
      operationId: UtmBuilderWeb.API.V1.AnalyticsController.report
      parameters:
        - description: ''
          in: query
          name: from
          required: false
          schema:
            format: date
            type: string
        - description: ''
          in: query
          name: to
          required: false
          schema:
            format: date
            type: string
        - description: ''
          in: query
          name: group_by
          required: false
          schema:
            enum:
              - day
              - country
              - device
              - referrer
              - utm_source
              - utm_medium
              - utm_campaign
              - utm_term
              - utm_content
              - trigger
              - event_type
              - destination
            type: string
        - description: ''
          in: query
          name: short_code
          required: false
          schema:
            type: string
        - description: ''
          in: query
          name: host
          required: false
          schema:
            type: string
        - description: ''
          in: query
          name: campaign_id
          required: false
          schema:
            type: integer
        - description: ''
          in: query
          name: tag
          required: false
          schema:
            type: string
        - description: ''
          in: query
          name: compare
          required: false
          schema:
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
          description: Report
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error
      callbacks: {}
components:
  schemas:
    Report:
      properties:
        capped:
          type: boolean
        comparison:
          description: >-
            Present only when compare=true: the previous period, or
            {unavailable: sentence}
          properties:
            change:
              properties:
                clicks:
                  nullable: true
                  type: integer
                conversions:
                  nullable: true
                  type: integer
                scans:
                  nullable: true
                  type: integer
                uniques:
                  nullable: true
                  type: integer
              type: object
            from:
              format: date
              type: string
            to:
              format: date
              type: string
            totals:
              properties:
                clicks:
                  type: integer
                conversions:
                  type: integer
                scans:
                  type: integer
                uniques:
                  type: integer
              type: object
            unavailable:
              type: string
          type: object
        from:
          format: date
          type: string
        group_by:
          type: string
        rows:
          items:
            additionalProperties: true
            type: object
          type: array
        to:
          format: date
          type: string
        totals:
          properties:
            clicks:
              type: integer
            conversions:
              type: integer
            scans:
              type: integer
            uniques:
              type: integer
            value:
              additionalProperties:
                type: string
              description: >-
                currency → decimal string, summed per currency; null when no
                conversion in the period carried a value. Never summed across
                currencies (spec 046)
              nullable: true
              type: object
          type: object
      title: Report
      type: object
    Error:
      description: Every refusal. `code` is the closed set of FR-019.
      properties:
        error:
          properties:
            code:
              enum:
                - unauthenticated
                - subscription_required
                - subscription_ended
                - missing_permission
                - role_forbids
                - plan_forbids
                - rate_limited
                - governance_refused
                - scanner_refused
                - limit_reached
                - duplicate_link
                - not_found
                - invalid_input
              type: string
            details:
              additionalProperties: true
              description: field → messages, on invalid_input
              nullable: true
              type: object
            message:
              type: string
            permission:
              nullable: true
              type: string
            retry_after_seconds:
              nullable: true
              type: integer
          required:
            - code
            - message
          type: object
      required:
        - error
      title: Error
      type: object
  securitySchemes:
    bearer:
      description: utmk_<lookup><secret>, minted on /tokens
      scheme: bearer
      type: http

````