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

# Link analytics

> Retrieve click analytics for a single link.



## OpenAPI

````yaml GET /links/{linkId}/analytics
openapi: 3.0.3
info:
  title: linkutm API
  version: 1.0.0
  description: >-
    REST API for linkutm — short links, UTM tagging, custom domains, folders,
    tags and click analytics.


    Every endpoint documented here is served under
    `https://api.linkutm.com/api/v1`.
servers:
  - url: https://api.linkutm.com/api/v1
    description: Local development
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Links
    description: Create, read, update and delete short links, individually or in bulk.
  - name: Domains
    description: Register and verify the custom domains short links are served from.
  - name: Folders
    description: Group links into folders.
  - name: Tags
    description: Label links and manage which links carry which tag.
  - name: Analytics
    description: Click analytics for the workspace and for individual links.
  - name: Imports
    description: Migrate links in from Short.io, Bitly and Rebrandly.
paths:
  /links/{linkId}/analytics:
    get:
      tags:
        - Analytics
      summary: Link analytics
      description: Retrieve click analytics for a single link.
      operationId: getLinkAnalytics
      parameters:
        - name: linkId
          in: path
          required: true
          description: Link ID.
          schema:
            type: string
            format: uuid
        - name: interval
          in: query
          required: false
          description: >-
            Preset date range: whole days up to the end of today (`24h` is the
            last 24 hours). Use this instead of `startDate` and `endDate`.
          schema:
            type: string
            enum:
              - 24h
              - 7d
              - 30d
              - 90d
              - 1y
            example: 30d
            default: 30d
        - name: timezone
          in: query
          required: false
          description: Time zone used to count `interval` days. Defaults to `Asia/Kolkata`.
          schema:
            type: string
            enum:
              - Asia/Kolkata
              - UTC
              - Africa/Abidjan
              - Africa/Accra
              - Africa/Addis_Ababa
              - Africa/Algiers
              - Africa/Asmara
              - Africa/Bamako
              - Africa/Bangui
              - Africa/Banjul
              - Africa/Bissau
              - Africa/Blantyre
              - Africa/Brazzaville
              - Africa/Bujumbura
              - Africa/Cairo
              - Africa/Casablanca
              - Africa/Ceuta
              - Africa/Conakry
              - Africa/Dakar
              - Africa/Dar_es_Salaam
              - Africa/Djibouti
              - Africa/Douala
              - Africa/El_Aaiun
              - Africa/Freetown
              - Africa/Gaborone
              - Africa/Harare
              - Africa/Johannesburg
              - Africa/Juba
              - Africa/Kampala
              - Africa/Khartoum
              - Africa/Kigali
              - Africa/Kinshasa
              - Africa/Lagos
              - Africa/Libreville
              - Africa/Lome
              - Africa/Luanda
              - Africa/Lubumbashi
              - Africa/Lusaka
              - Africa/Malabo
              - Africa/Maputo
              - Africa/Maseru
              - Africa/Mbabane
              - Africa/Mogadishu
              - Africa/Monrovia
              - Africa/Nairobi
              - Africa/Ndjamena
              - Africa/Niamey
              - Africa/Nouakchott
              - Africa/Ouagadougou
              - Africa/Porto-Novo
              - Africa/Sao_Tome
              - Africa/Tripoli
              - Africa/Tunis
              - Africa/Windhoek
              - America/Adak
              - America/Anchorage
              - America/Anguilla
              - America/Antigua
              - America/Araguaina
              - America/Argentina/La_Rioja
              - America/Argentina/Rio_Gallegos
              - America/Argentina/Salta
              - America/Argentina/San_Juan
              - America/Argentina/San_Luis
              - America/Argentina/Tucuman
              - America/Argentina/Ushuaia
              - America/Aruba
              - America/Asuncion
              - America/Bahia
              - America/Bahia_Banderas
              - America/Barbados
              - America/Belem
              - America/Belize
              - America/Blanc-Sablon
              - America/Boa_Vista
              - America/Bogota
              - America/Boise
              - America/Buenos_Aires
              - America/Cambridge_Bay
              - America/Campo_Grande
              - America/Cancun
              - America/Caracas
              - America/Catamarca
              - America/Cayenne
              - America/Cayman
              - America/Chicago
              - America/Chihuahua
              - America/Ciudad_Juarez
              - America/Coral_Harbour
              - America/Cordoba
              - America/Costa_Rica
              - America/Coyhaique
              - America/Creston
              - America/Cuiaba
              - America/Curacao
              - America/Danmarkshavn
              - America/Dawson
              - America/Dawson_Creek
              - America/Denver
              - America/Detroit
              - America/Dominica
              - America/Edmonton
              - America/Eirunepe
              - America/El_Salvador
              - America/Fort_Nelson
              - America/Fortaleza
              - America/Glace_Bay
              - America/Nuuk
              - America/Goose_Bay
              - America/Grand_Turk
              - America/Grenada
              - America/Guadeloupe
              - America/Guatemala
              - America/Guayaquil
              - America/Guyana
              - America/Halifax
              - America/Havana
              - America/Hermosillo
              - America/Indiana/Knox
              - America/Indiana/Marengo
              - America/Indiana/Petersburg
              - America/Indiana/Tell_City
              - America/Indiana/Vevay
              - America/Indiana/Vincennes
              - America/Indiana/Winamac
              - America/Indianapolis
              - America/Inuvik
              - America/Iqaluit
              - America/Jamaica
              - America/Jujuy
              - America/Juneau
              - America/Kentucky/Monticello
              - America/Kralendijk
              - America/La_Paz
              - America/Lima
              - America/Los_Angeles
              - America/Louisville
              - America/Lower_Princes
              - America/Maceio
              - America/Managua
              - America/Manaus
              - America/Marigot
              - America/Martinique
              - America/Matamoros
              - America/Mazatlan
              - America/Mendoza
              - America/Menominee
              - America/Merida
              - America/Metlakatla
              - America/Mexico_City
              - America/Miquelon
              - America/Moncton
              - America/Monterrey
              - America/Montevideo
              - America/Montserrat
              - America/Nassau
              - America/New_York
              - America/Nome
              - America/Noronha
              - America/North_Dakota/Beulah
              - America/North_Dakota/Center
              - America/North_Dakota/New_Salem
              - America/Ojinaga
              - America/Panama
              - America/Paramaribo
              - America/Phoenix
              - America/Port-au-Prince
              - America/Port_of_Spain
              - America/Porto_Velho
              - America/Puerto_Rico
              - America/Punta_Arenas
              - America/Rankin_Inlet
              - America/Recife
              - America/Regina
              - America/Resolute
              - America/Rio_Branco
              - America/Santarem
              - America/Santiago
              - America/Santo_Domingo
              - America/Sao_Paulo
              - America/Scoresbysund
              - America/Sitka
              - America/St_Barthelemy
              - America/St_Johns
              - America/St_Kitts
              - America/St_Lucia
              - America/St_Thomas
              - America/St_Vincent
              - America/Swift_Current
              - America/Tegucigalpa
              - America/Thule
              - America/Tijuana
              - America/Toronto
              - America/Tortola
              - America/Vancouver
              - America/Whitehorse
              - America/Winnipeg
              - America/Yakutat
              - Antarctica/Casey
              - Antarctica/Davis
              - Antarctica/DumontDUrville
              - Antarctica/Macquarie
              - Antarctica/Mawson
              - Antarctica/McMurdo
              - Antarctica/Palmer
              - Antarctica/Rothera
              - Antarctica/Syowa
              - Antarctica/Troll
              - Antarctica/Vostok
              - Arctic/Longyearbyen
              - Asia/Aden
              - Asia/Almaty
              - Asia/Amman
              - Asia/Anadyr
              - Asia/Aqtau
              - Asia/Aqtobe
              - Asia/Ashgabat
              - Asia/Atyrau
              - Asia/Baghdad
              - Asia/Bahrain
              - Asia/Baku
              - Asia/Bangkok
              - Asia/Barnaul
              - Asia/Beirut
              - Asia/Bishkek
              - Asia/Brunei
              - Asia/Chita
              - Asia/Colombo
              - Asia/Damascus
              - Asia/Dhaka
              - Asia/Dili
              - Asia/Dubai
              - Asia/Dushanbe
              - Asia/Famagusta
              - Asia/Gaza
              - Asia/Hebron
              - Asia/Hong_Kong
              - Asia/Hovd
              - Asia/Irkutsk
              - Asia/Jakarta
              - Asia/Jayapura
              - Asia/Jerusalem
              - Asia/Kabul
              - Asia/Kamchatka
              - Asia/Karachi
              - Asia/Kathmandu
              - Asia/Khandyga
              - Asia/Krasnoyarsk
              - Asia/Kuala_Lumpur
              - Asia/Kuching
              - Asia/Kuwait
              - Asia/Macau
              - Asia/Magadan
              - Asia/Makassar
              - Asia/Manila
              - Asia/Muscat
              - Asia/Nicosia
              - Asia/Novokuznetsk
              - Asia/Novosibirsk
              - Asia/Omsk
              - Asia/Oral
              - Asia/Phnom_Penh
              - Asia/Pontianak
              - Asia/Pyongyang
              - Asia/Qatar
              - Asia/Qostanay
              - Asia/Qyzylorda
              - Asia/Yangon
              - Asia/Riyadh
              - Asia/Ho_Chi_Minh
              - Asia/Sakhalin
              - Asia/Samarkand
              - Asia/Seoul
              - Asia/Shanghai
              - Asia/Singapore
              - Asia/Srednekolymsk
              - Asia/Taipei
              - Asia/Tashkent
              - Asia/Tbilisi
              - Asia/Tehran
              - Asia/Thimphu
              - Asia/Tokyo
              - Asia/Tomsk
              - Asia/Ulaanbaatar
              - Asia/Urumqi
              - Asia/Ust-Nera
              - Asia/Vientiane
              - Asia/Vladivostok
              - Asia/Yakutsk
              - Asia/Yekaterinburg
              - Asia/Yerevan
              - Atlantic/Azores
              - Atlantic/Bermuda
              - Atlantic/Canary
              - Atlantic/Cape_Verde
              - Atlantic/Faroe
              - Atlantic/Madeira
              - Atlantic/Reykjavik
              - Atlantic/South_Georgia
              - Atlantic/St_Helena
              - Atlantic/Stanley
              - Australia/Adelaide
              - Australia/Brisbane
              - Australia/Broken_Hill
              - Australia/Darwin
              - Australia/Eucla
              - Australia/Hobart
              - Australia/Lindeman
              - Australia/Lord_Howe
              - Australia/Melbourne
              - Australia/Perth
              - Australia/Sydney
              - Europe/Amsterdam
              - Europe/Andorra
              - Europe/Astrakhan
              - Europe/Athens
              - Europe/Belgrade
              - Europe/Berlin
              - Europe/Bratislava
              - Europe/Brussels
              - Europe/Bucharest
              - Europe/Budapest
              - Europe/Busingen
              - Europe/Chisinau
              - Europe/Copenhagen
              - Europe/Dublin
              - Europe/Gibraltar
              - Europe/Guernsey
              - Europe/Helsinki
              - Europe/Isle_of_Man
              - Europe/Istanbul
              - Europe/Jersey
              - Europe/Kaliningrad
              - Europe/Kyiv
              - Europe/Kirov
              - Europe/Lisbon
              - Europe/Ljubljana
              - Europe/London
              - Europe/Luxembourg
              - Europe/Madrid
              - Europe/Malta
              - Europe/Mariehamn
              - Europe/Minsk
              - Europe/Monaco
              - Europe/Moscow
              - Europe/Oslo
              - Europe/Paris
              - Europe/Podgorica
              - Europe/Prague
              - Europe/Riga
              - Europe/Rome
              - Europe/Samara
              - Europe/San_Marino
              - Europe/Sarajevo
              - Europe/Saratov
              - Europe/Simferopol
              - Europe/Skopje
              - Europe/Sofia
              - Europe/Stockholm
              - Europe/Tallinn
              - Europe/Tirane
              - Europe/Ulyanovsk
              - Europe/Vaduz
              - Europe/Vatican
              - Europe/Vienna
              - Europe/Vilnius
              - Europe/Volgograd
              - Europe/Warsaw
              - Europe/Zagreb
              - Europe/Zurich
              - Indian/Antananarivo
              - Indian/Chagos
              - Indian/Christmas
              - Indian/Cocos
              - Indian/Comoro
              - Indian/Kerguelen
              - Indian/Mahe
              - Indian/Maldives
              - Indian/Mauritius
              - Indian/Mayotte
              - Indian/Reunion
              - Pacific/Apia
              - Pacific/Auckland
              - Pacific/Bougainville
              - Pacific/Chatham
              - Pacific/Easter
              - Pacific/Efate
              - Pacific/Kanton
              - Pacific/Fakaofo
              - Pacific/Fiji
              - Pacific/Funafuti
              - Pacific/Galapagos
              - Pacific/Gambier
              - Pacific/Guadalcanal
              - Pacific/Guam
              - Pacific/Honolulu
              - Pacific/Kiritimati
              - Pacific/Kosrae
              - Pacific/Kwajalein
              - Pacific/Majuro
              - Pacific/Marquesas
              - Pacific/Midway
              - Pacific/Nauru
              - Pacific/Niue
              - Pacific/Norfolk
              - Pacific/Noumea
              - Pacific/Pago_Pago
              - Pacific/Palau
              - Pacific/Pitcairn
              - Pacific/Pohnpei
              - Pacific/Port_Moresby
              - Pacific/Rarotonga
              - Pacific/Saipan
              - Pacific/Tahiti
              - Pacific/Tarawa
              - Pacific/Tongatapu
              - Pacific/Chuuk
              - Pacific/Wake
              - Pacific/Wallis
            example: Asia/Kolkata
        - name: startDate
          in: query
          required: false
          description: >-
            Start date in `YYYY-MM-DD` format, e.g. `2026-07-01`. Required when
            `interval` is not sent.
          schema:
            type: string
            format: date
            example: '2026-07-01'
        - name: endDate
          in: query
          required: false
          description: >-
            End date in `YYYY-MM-DD` format, e.g. `2026-07-31`. Required when
            `interval` is not sent.
          schema:
            type: string
            format: date
            example: '2026-07-31'
      responses:
        '200':
          description: Click analytics for the link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalClicks:
                    type: integer
                  uniqueVisitors:
                    type: integer
                  clicksOverTime:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickSeriesPoint'
                  topCountries:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
                  topRegions:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
                  topCities:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
                  topReferrers:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
                  deviceBreakdown:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
                  browserBreakdown:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
                  osBreakdown:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClickCountRow'
        '400':
          description: >-
            Validation failed, or a required header or query parameter is
            missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 400
                message:
                  - startDate must be a valid ISO 8601 date
                error: Bad Request
        '401':
          description: Missing, malformed, expired or revoked credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 401
                message: Invalid or expired API key
                error: Unauthorized
        '403':
          description: >-
            The caller lacks `analytics.view`, the range starts before the
            plan's retention window, or the monthly click allowance is used up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 403
                message: >-
                  You've used all your monthly clicks. Upgrade your plan to view
                  analytics.
                error: Forbidden
        '404':
          description: The resource does not exist, or belongs to another workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 404
                message: Link not found
                error: Not Found
        '500':
          description: Unexpected server error. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 500
                message: Internal server error
components:
  schemas:
    ClickSeriesPoint:
      type: object
      properties:
        date:
          type: string
          format: date
          example: '2026-08-01'
        clicks:
          type: integer
    ClickCountRow:
      type: object
      properties:
        name:
          type: string
        clicks:
          type: integer
    Error:
      type: object
      description: >-
        Standard NestJS error envelope. `message` is a string for exceptions
        thrown by a service, and an array of strings when the global
        ValidationPipe rejects the body.
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          description: Human-readable reason, or a list of field-level validation errors.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Link not found
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Workspace API key, sent as `Authorization: Bearer lk_live_…`.'
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Dashboard session token from `POST /auth/login`.

````

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