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

# Retrieve analytics

> Requires the `analytics:read` scope. On Free, this is clicks by day for up to the last 7
days, which is also the default range there; anything else returns `403 plan_required`.
Days are in UTC. `total` always counts every
click in the range, also when `data` is cut at 1000 rows (`truncated: true`).




## OpenAPI

````yaml GET /links/{id}/analytics
openapi: 3.1.0
info:
  title: URLdn API
  version: 1.0.0
  description: >
    Create and manage short links, tags and custom domains, read click
    analytics, generate

    QR codes and ask the AI analyst. Included on every plan, with limits by
    plan. Limits apply

    to your whole account, across all its keys.


    Keep API keys on your server: anything in front-end code can be read by
    anyone.
servers:
  - url: https://api.urldn.com/v1
security:
  - apiKey: []
tags:
  - name: Links
  - name: Tags
  - name: Domains
  - name: Analytics
  - name: QR codes
  - name: AI analyst
  - name: Account
paths:
  /links/{id}/analytics:
    parameters:
      - $ref: '#/components/parameters/LinkId'
    get:
      tags:
        - Analytics
      summary: Retrieve analytics
      description: >
        Requires the `analytics:read` scope. On Free, this is clicks by day for
        up to the last 7

        days, which is also the default range there; anything else returns `403
        plan_required`.

        Days are in UTC. `total` always counts every

        click in the range, also when `data` is cut at 1000 rows (`truncated:
        true`).
      operationId: getLinkAnalytics
      parameters:
        - name: range
          in: query
          schema:
            type: string
            enum:
              - 24h
              - 7d
              - 30d
              - 90d
              - 365d
              - all
            default: 30d
        - name: groupBy
          in: query
          schema:
            type: string
            enum:
              - day
              - country
              - device
              - referrer
            default: day
      responses:
        '200':
          description: Click counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    LinkId:
      name: id
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-f0-9]{24}$
  schemas:
    Analytics:
      type: object
      required:
        - linkId
        - range
        - start
        - end
        - groupBy
        - total
        - data
        - truncated
      properties:
        linkId:
          type: string
        range:
          type: string
        start:
          type:
            - string
            - 'null'
          format: date-time
        end:
          type: string
          format: date-time
        groupBy:
          type: string
          enum:
            - day
            - country
            - device
            - referrer
        total:
          type: integer
        data:
          type: array
          items:
            type: object
            required:
              - key
              - clicks
            properties:
              key:
                type: string
                examples:
                  - '2026-11-02'
                  - US
                  - mobile
                  - Direct
              clicks:
                type: integer
        truncated:
          type: boolean
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: A stable machine-readable code
          examples:
            - quota_exceeded
        message:
          type: string
        details:
          type: object
          additionalProperties: true
  responses:
    BadRequest:
      description: >-
        `invalid_request`, `invalid_json`, `invalid_cursor` or
        `blocked_destination`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: '`missing_api_key`, `invalid_api_key` or `revoked_api_key`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: '`plan_required`, `insufficient_scope` or `domain_not_allowed`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: '`not_found`. Anything in another account also returns this.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        `rate_limited`, `monthly_quota_exceeded` or `too_many_auth_failures`.
        Wait for `Retry-After` seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer urldn_live_...`'

````

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