> ## Documentation Index > Fetch the complete documentation index at: https://docs.spoo.me/llms.txt > Use this file to discover all available pages before exploring further. # Link Statistics > Get click statistics for a single URL you own. The same aggregated analytics as `GET /stats`, pre-scoped to one link — the response additionally echoes the link's `url_id` and `alias`. Custom-domain links are safe here: clicks are matched by URL id, so a same-alias link on another domain can never bleed in. **Authentication**: Required — you must own the URL. **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: 60/min, 5,000/day **Grouping Dimensions**: `time`, `browser`, `os`, `device`, `country`, `city`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign` **Metrics**: `clicks`, `unique_clicks` **Filtering**: Filter by `browser`, `os`, `device`, `country`, `city`, `referrer`, or the `utm_*` tags using query params or a JSON `filters` object. Link-identity filters (`short_code`, `url_id`) do not exist here — the path already selects the link. **Errors**: - `400` — malformed id (not a valid ObjectId) - `404` — no URL with that id in your account. A URL owned by someone else answers identically; this endpoint never confirms foreign ids. ## OpenAPI ````yaml /openapi-v1.json get /api/v1/stats/links/{url_id} openapi: 3.1.0 info: title: spoo.me description: >- REST API for spoo.me — free and open-source URL shortening service serving 400k+ redirects/day. Authenticate using either: - **API Key**: `Authorization: Bearer spoo_` - **JWT Token**: `Authorization: Bearer ` (obtained via /auth/login) - **Session Cookie**: `access_token` cookie (set automatically on login) contact: name: spoo.me url: https://spoo.me/contact email: support@spoo.me license: name: AGPL-3.0 url: https://github.com/spoo-me/spoo/blob/main/LICENSE version: 1.0.0 servers: - url: https://spoo.me description: Production security: - ApiKeyAuth: [] - JWTAuth: [] tags: - name: URL Shortening description: Create new shortened URLs - name: Link Management description: List, update, and delete your shortened URLs - name: Statistics description: Click analytics and data export - name: API Keys description: Create and manage API keys for programmatic access - name: Authentication description: Login, register, password management, and email verification - name: OAuth description: OAuth provider login, linking, and unlinking - name: System description: Health checks and server metrics paths: /api/v1/stats/links/{url_id}: get: tags: - Statistics summary: Link Statistics description: |- Get click statistics for a single URL you own. The same aggregated analytics as `GET /stats`, pre-scoped to one link — the response additionally echoes the link's `url_id` and `alias`. Custom-domain links are safe here: clicks are matched by URL id, so a same-alias link on another domain can never bleed in. **Authentication**: Required — you must own the URL. **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: 60/min, 5,000/day **Grouping Dimensions**: `time`, `browser`, `os`, `device`, `country`, `city`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign` **Metrics**: `clicks`, `unique_clicks` **Filtering**: Filter by `browser`, `os`, `device`, `country`, `city`, `referrer`, or the `utm_*` tags using query params or a JSON `filters` object. Link-identity filters (`short_code`, `url_id`) do not exist here — the path already selects the link. **Errors**: - `400` — malformed id (not a valid ObjectId) - `404` — no URL with that id in your account. A URL owned by someone else answers identically; this endpoint never confirms foreign ids. operationId: getLinkStats parameters: - name: url_id in: path required: true schema: type: string description: Unique identifier of the URL (MongoDB ObjectId). title: Url Id description: Unique identifier of the URL (MongoDB ObjectId). - name: start_date in: query required: false schema: anyOf: - type: string maxLength: 50 - type: 'null' description: >- Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`. examples: - '2025-01-01T00:00:00Z' title: Start Date description: >- Start of time range. Accepts ISO 8601 datetime string (e.g., `2025-01-01T00:00:00Z`) or Unix timestamp in seconds (e.g., `1735689600`). If omitted, defaults to 7 days before `end_date`. - name: end_date in: query required: false schema: anyOf: - type: string maxLength: 50 - type: 'null' description: >- End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now. examples: - '2025-12-31T23:59:59Z' title: End Date description: >- End of time range. Accepts ISO 8601 datetime string (e.g., `2025-12-31T23:59:59Z`) or Unix timestamp in seconds (e.g., `1767225599`). If omitted, defaults to now. - name: group_by in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: >- Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted. **Available dimensions:** - `time` — group by time buckets (day/week/month, auto-selected based on range) - `browser` — group by browser name (e.g., Chrome, Firefox, Safari) - `os` — group by operating system (e.g., Windows, macOS, Linux) - `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`) - `country` — group by country - `city` — group by city - `referrer` — group by referrer URL - `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`) - `utm_medium` — group by the `utm_medium` tag - `utm_campaign` — group by the `utm_campaign` tag Multiple dimensions can be combined: `time,browser` returns time series broken down by browser. examples: - time,browser - country - time,country,browser title: Group By description: >- Comma-separated grouping dimensions for the statistics breakdown. Defaults to `time` if omitted. **Available dimensions:** - `time` — group by time buckets (day/week/month, auto-selected based on range) - `browser` — group by browser name (e.g., Chrome, Firefox, Safari) - `os` — group by operating system (e.g., Windows, macOS, Linux) - `device` — group by device type (`mobile`, `tablet`, `desktop`, `unknown`) - `country` — group by country - `city` — group by city - `referrer` — group by referrer URL - `utm_source` — group by the `utm_source` tag on the short link (untagged clicks appear as `(none)`) - `utm_medium` — group by the `utm_medium` tag - `utm_campaign` — group by the `utm_campaign` tag Multiple dimensions can be combined: `time,browser` returns time series broken down by browser. - name: metrics in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: >- Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted. **Available metrics:** - `clicks` — total click count - `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent) examples: - clicks,unique_clicks - clicks title: Metrics description: >- Comma-separated metrics to include. Defaults to `clicks,unique_clicks` if omitted. **Available metrics:** - `clicks` — total click count - `unique_clicks` — unique visitor count (deduplicated by IP + User-Agent) - name: timezone in: query required: false schema: type: string maxLength: 50 description: >- IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`. examples: - UTC - America/New_York default: UTC title: Timezone description: >- IANA timezone name for time-based grouping and output formatting (e.g., `UTC`, `America/New_York`, `Asia/Kolkata`). Defaults to `UTC`. - name: filters in: query required: false schema: anyOf: - type: string maxLength: 5000 - type: 'null' description: >- **Method 1: JSON Filters Object** JSON string containing dimension filters. Format: `{"dimension": ["value1", "value2"]}` **Available filter dimensions:** - `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge) - `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android) - `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`) - `country` — Filter by country name (e.g., United States, Canada, Germany) - `city` — Filter by city name (e.g., New York, London, Mumbai) - `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com) - `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks **Value format:** Array of strings for each dimension. **Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database. **Examples:** - `{"browser": ["Chrome", "Firefox"]}` — Chrome OR Firefox clicks - `{"country": ["United States", "Canada"], "browser": ["Chrome"]}` — US/CA clicks from Chrome **Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below). examples: - '{"browser":["Chrome","Firefox"]}' - '{"country":["United States","Canada"],"browser":["Chrome"]}' title: Filters description: >- **Method 1: JSON Filters Object** JSON string containing dimension filters. Format: `{"dimension": ["value1", "value2"]}` **Available filter dimensions:** - `browser` — Filter by browser name (e.g., Chrome, Firefox, Safari, Edge) - `os` — Filter by operating system (e.g., Windows, macOS, Linux, iOS, Android) - `device` — Filter by device type (`mobile`, `tablet`, `desktop`, `unknown`) - `country` — Filter by country name (e.g., United States, Canada, Germany) - `city` — Filter by city name (e.g., New York, London, Mumbai) - `referrer` — Filter by referrer URL (e.g., https://google.com, https://twitter.com) - `utm_source` / `utm_medium` / `utm_campaign` — Filter by campaign tags; `(none)` matches untagged clicks **Value format:** Array of strings for each dimension. **Important:** Filter values are case-sensitive. Use exact capitalization as stored in the database. **Examples:** - `{"browser": ["Chrome", "Firefox"]}` — Chrome OR Firefox clicks - `{"country": ["United States", "Canada"], "browser": ["Chrome"]}` — US/CA clicks from Chrome **Alternative:** You can also pass filters as individual query parameters (see `browser`, `os`, `country`, `city`, `referrer` parameters below). - name: browser in: query required: false schema: anyOf: - type: string maxLength: 500 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated browser names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - Chrome,Firefox title: Browser description: >- **Method 2: Individual Filter Parameter** Comma-separated browser names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Common values include: Chrome, Firefox, Safari, Edge, Opera, Samsung Internet. **Note:** Both `filters` JSON and individual parameters can be combined. - name: os in: query required: false schema: anyOf: - type: string maxLength: 500 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated operating system names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - Windows,macOS title: Os description: >- **Method 2: Individual Filter Parameter** Comma-separated operating system names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Common values include: Windows, macOS, Linux, iOS, Android, Chrome OS. **Note:** Both `filters` JSON and individual parameters can be combined. - name: device in: query required: false schema: anyOf: - type: string maxLength: 200 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated device types. Alternative to using the `filters` JSON parameter. **Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - mobile,desktop title: Device description: >- **Method 2: Individual Filter Parameter** Comma-separated device types. Alternative to using the `filters` JSON parameter. **Values:** `mobile`, `tablet`, `desktop`, `unknown`. `unknown` also matches clicks recorded before device tracking existed. **Note:** Both `filters` JSON and individual parameters can be combined. - name: country in: query required: false schema: anyOf: - type: string maxLength: 1000 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated country names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan). **Note:** Both `filters` JSON and individual parameters can be combined. examples: - United States,Germany title: Country description: >- **Method 2: Individual Filter Parameter** Comma-separated country names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Use full country names as stored in the database (e.g., United States, Canada, United Kingdom, India, Germany, France, Japan). **Note:** Both `filters` JSON and individual parameters can be combined. - name: city in: query required: false schema: anyOf: - type: string maxLength: 1000 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated city names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Use exact capitalization as stored in the database. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - San Francisco,Berlin title: City description: >- **Method 2: Individual Filter Parameter** Comma-separated city names. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Use exact capitalization as stored in the database. **Note:** Both `filters` JSON and individual parameters can be combined. - name: referrer in: query required: false schema: anyOf: - type: string maxLength: 2000 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated referrer URLs. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Include the full URL including protocol. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - https://google.com,https://twitter.com title: Referrer description: >- **Method 2: Individual Filter Parameter** Comma-separated referrer URLs. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. Include the full URL including protocol. **Note:** Both `filters` JSON and individual parameters can be combined. - name: utm_source in: query required: false schema: anyOf: - type: string maxLength: 1000 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated campaign tag values. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. `(none)` matches clicks with no tag. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - newsletter,twitter title: Utm Source description: >- **Method 2: Individual Filter Parameter** Comma-separated campaign tag values. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. `(none)` matches clicks with no tag. **Note:** Both `filters` JSON and individual parameters can be combined. - name: utm_medium in: query required: false schema: anyOf: - type: string maxLength: 1000 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated campaign tag values. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. `(none)` matches clicks with no tag. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - email,social title: Utm Medium description: >- **Method 2: Individual Filter Parameter** Comma-separated campaign tag values. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. `(none)` matches clicks with no tag. **Note:** Both `filters` JSON and individual parameters can be combined. - name: utm_campaign in: query required: false schema: anyOf: - type: string maxLength: 1000 - type: 'null' description: >- **Method 2: Individual Filter Parameter** Comma-separated campaign tag values. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. `(none)` matches clicks with no tag. **Note:** Both `filters` JSON and individual parameters can be combined. examples: - summer-launch title: Utm Campaign description: >- **Method 2: Individual Filter Parameter** Comma-separated campaign tag values. Alternative to using the `filters` JSON parameter. **Important:** Values are case-sensitive. `(none)` matches clicks with no tag. **Note:** Both `filters` JSON and individual parameters can be combined. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LinkStatsResponse' '400': description: Bad Request — invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized — missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden — insufficient permissions or scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: LinkStatsResponse: properties: scope: $ref: '#/components/schemas/StatsScope' filters: additionalProperties: items: type: string type: array type: object title: Filters group_by: items: type: string type: array title: Group By timezone: type: string title: Timezone time_range: $ref: '#/components/schemas/StatsTimeRange' summary: $ref: '#/components/schemas/StatsSummary' metrics: additionalProperties: items: additionalProperties: true type: object type: array type: object title: Metrics description: >- Keyed by '{metric}_by_{dimension}' (e.g. 'clicks_by_browser', 'unique_clicks_by_time'). Each value is a list of data-point objects whose keys are the dimension name, the metric name, and '{metric}_percentage'. generated_at: anyOf: - type: string format: date-time - type: 'null' title: Generated At api_version: anyOf: - type: string - type: 'null' title: Api Version short_code: anyOf: - type: string - type: 'null' title: Short Code time_bucket_info: anyOf: - $ref: '#/components/schemas/TimeBucketInfo' - type: 'null' computed_metrics: anyOf: - $ref: '#/components/schemas/ComputedMetrics' - type: 'null' url_id: type: string title: Url Id alias: type: string title: Alias type: object required: - scope - filters - group_by - timezone - time_range - summary - url_id - alias title: LinkStatsResponse description: |- Response body for GET /api/v1/stats/links/{url_id}. The standard stats wire plus the identity of the selected link. ``scope`` stays ``all`` — the link is part of the owner's aggregate. ErrorResponse: properties: error: type: string title: Error code: type: string title: Code field: anyOf: - type: string - type: 'null' title: Field details: anyOf: - {} - type: 'null' title: Details type: object required: - error - code title: ErrorResponse description: Standard error JSON body produced by the AppError exception handler. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError StatsScope: type: string enum: - all - anon title: StatsScope description: |- Stats wire scope. Response-only: the ``scope`` request parameter no longer exists (auth is mandatory), but the response wire keeps its ``scope`` key and the public stats endpoint's frozen contract still carries ``anon``. StatsTimeRange: properties: start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date end_date: anyOf: - type: string format: date-time - type: 'null' title: End Date type: object title: StatsTimeRange description: Time range metadata inside StatsResponse. StatsSummary: properties: total_clicks: type: integer title: Total Clicks unique_clicks: type: integer title: Unique Clicks first_click: anyOf: - type: string format: date-time - type: 'null' title: First Click last_click: anyOf: - type: string format: date-time - type: 'null' title: Last Click avg_redirection_time: anyOf: - type: number - type: 'null' title: Avg Redirection Time type: object required: - total_clicks - unique_clicks title: StatsSummary description: Summary statistics block inside StatsResponse. TimeBucketInfo: properties: strategy: type: string title: Strategy mongo_format: type: string title: Mongo Format display_format: type: string title: Display Format timezone: type: string title: Timezone interval_minutes: anyOf: - type: integer - type: 'null' title: Interval Minutes type: object required: - strategy - mongo_format - display_format - timezone title: TimeBucketInfo description: Time bucketing metadata — only present when 'time' is in group_by. ComputedMetrics: properties: unique_click_rate: type: number title: Unique Click Rate repeat_click_rate: type: number title: Repeat Click Rate average_clicks_per_visitor: type: number title: Average Clicks Per Visitor type: object required: - unique_click_rate - repeat_click_rate - average_clicks_per_visitor title: ComputedMetrics description: Optional computed metrics added by format_stats_response_with_metadata. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: spoo_ description: 'API key authentication. Pass your key as: `Bearer spoo_`' JWTAuth: type: http scheme: bearer bearerFormat: JWT description: 'JWT access token from /auth/login. Pass as: `Bearer `' ````