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

# Retrieve Click Analytics

> Returns raw click analytics for the specified date range. Results are scoped to the organization and optionally filtered by workspace or link.

Returns raw click events for the supplied date range. Results are scoped to the organization linked to your API token and, optionally, filtered to a specific workspace or  link.

### Request body essentials

* `start` / `end` — inclusive `YYYY-MM-DD` values defining the window to analyse.
* `workspace_id` — optional workspace filter (defaults to the first workspace available to the token).
* `url_id` — optional link filter to drill into a single asset.

The system normalises timestamps to the requesting user's timezone when one is configured, otherwise UTC is used.

### Response payload

Each item in `data` represents an individual click with the following fields:

* `id` — primary key of the analytics record.
* `workspace_id` / `organization_id` — ownership metadata.
* `url_id` / `url_slug` / `domain` — link identifiers to help you join with internal datasets.
* `device_type`, `platform`, `browser` — resolved client information.
* `country` and `referrer` — geo and attribution context (when available).
* `created_at` — timestamp of the event.

Use this endpoint when you need the full fidelity log of clicks (for example exporting into a warehouse).


## OpenAPI

````yaml POST /v1/analytics
openapi: 3.1.0
info:
  title: ShortPen API
  version: 1.0.0
  description: >-
    Create branded links, fetch organization resources, and pull analytics
    programmatically with the ShortPen REST API.
servers:
  - url: https://{environment}.shortpen.com
    description: ShortPen API host
    variables:
      environment:
        default: api
        enum:
          - api
          - staging-api
security: []
tags:
  - name: Core
    description: Utility endpoints for checking service health.
  - name: Authentication
    description: Endpoints that return identity, limits, and feature availability.
  - name: Links
    description: Create, edit, and list links and their auxiliary assets like QR codes.
  - name: Resources
    description: >-
      Lookup supporting entities such as domains, workspaces, folders, and
      pixels.
  - name: Analytics
    description: Retrieve click analytics and raw tracking events.
paths:
  /v1/analytics:
    post:
      tags:
        - Analytics
      summary: Retrieve click analytics
      description: >-
        Returns raw click analytics for the specified date range. Results are
        scoped to the organization and optionally filtered by workspace or link.
      operationId: getAnalytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsRequest'
            examples:
              workspaceSummary:
                summary: Workspace analytics for a week
                value:
                  workspace_id: 24
                  start: '2025-01-01'
                  end: '2025-01-07'
              linkDeepDive:
                summary: Single link analytics
                value:
                  workspace_id: 24
                  url_id: 501
                  start: '2025-01-01'
                  end: '2025-01-31'
      responses:
        '200':
          description: Analytics events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    AnalyticsRequest:
      type: object
      properties:
        workspace_id:
          type: integer
          description: Workspace scope. Defaults to the first workspace when omitted.
        start:
          type: string
          format: date
          description: Inclusive start date for the time range.
        end:
          type: string
          format: date
          description: Inclusive end date for the time range.
        url_id:
          type: integer
          description: Optional link ID filter to narrow analytics.
      required:
        - start
        - end
    AnalyticsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status_code:
          type: integer
          example: 200
        message:
          type: string
          example: ''
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsEvent'
      required:
        - success
        - status_code
        - data
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status_code:
          type: integer
          example: 401
        message:
          type: string
          example: There was an error while processing your request.
        data:
          description: Optional payload returned for additional context.
          nullable: true
      required:
        - success
        - status_code
        - message
    AnalyticsEvent:
      type: object
      properties:
        id:
          type: integer
          example: 7301
        workspace_id:
          type: integer
          example: 24
        organization_id:
          type: integer
          example: 3
        url_id:
          type: integer
          example: 501
        domain:
          type: string
          example: go.shortpen.com
        url_slug:
          type: string
          example: summer-2025
        device_type:
          type: string
          example: mobile
        platform:
          type: string
          example: iOS
        browser:
          type: string
          example: Safari
        country:
          type: string
          example: US
        referrer:
          type: string
          example: https://news.example.com
        created_at:
          type: string
          format: date-time
      required:
        - id
        - workspace_id
        - organization_id
        - url_id
        - domain
        - created_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Personal Access Token

````