> ## 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. # URL Statistics > Get click statistics for URLs. Retrieve aggregated click analytics with flexible grouping, filtering, and time-range options. Results are computed in a single database round-trip using `$facet` aggregation. **Authentication**: Optional for `scope=anon` (public stats on a single URL); required for `scope=all` (all URLs owned by the user). **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: - Authenticated: 60/min, 5,000/day - Anonymous: 20/min, 1,000/day **Scopes**: - `scope=anon` + `short_code=` — public stats for one URL (if stats are not private) - `scope=all` — aggregate stats across all URLs owned by the authenticated user **Grouping Dimensions**: `time`, `browser`, `os`, `country`, `city`, `referrer`, `short_code` **Metrics**: `clicks`, `unique_clicks` **Filtering**: Filter by `browser`, `os`, `country`, `city`, `referrer`, or `short_code` using query params or a JSON `filters` object. ## OpenAPI ````yaml /openapi-v1.json get /api/v1/stats 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: get: tags: - Statistics summary: URL Statistics description: >- Get click statistics for URLs. Retrieve aggregated click analytics with flexible grouping, filtering, and time-range options. Results are computed in a single database round-trip using `$facet` aggregation. **Authentication**: Optional for `scope=anon` (public stats on a single URL); required for `scope=all` (all URLs owned by the user). **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: - Authenticated: 60/min, 5,000/day - Anonymous: 20/min, 1,000/day **Scopes**: - `scope=anon` + `short_code=` — public stats for one URL (if stats are not private) - `scope=all` — aggregate stats across all URLs owned by the authenticated user **Grouping Dimensions**: `time`, `browser`, `os`, `country`, `city`, `referrer`, `short_code` **Metrics**: `clicks`, `unique_clicks` **Filtering**: Filter by `browser`, `os`, `country`, `city`, `referrer`, or `short_code` using query params or a JSON `filters` object. operationId: getStats parameters: - name: scope in: query required: true schema: enum: - all - anon type: string description: >- Statistics scope: `all` (authenticated only) or `anon` (public access). - `all` — aggregate stats across all URLs owned by the authenticated user. Requires authentication. - `anon` — public stats for a single URL. Requires `short_code` parameter. No authentication needed (unless stats are private). title: Scope description: >- Statistics scope: `all` (authenticated only) or `anon` (public access). - `all` — aggregate stats across all URLs owned by the authenticated user. Requires authentication. - `anon` — public stats for a single URL. Requires `short_code` parameter. No authentication needed (unless stats are private). - name: short_code in: query required: false schema: anyOf: - type: string - type: 'null' description: >- URL alias to query stats for. **Required** when `scope=anon`. When `scope=all`, this is optional and filters stats to a specific URL. examples: - mylink title: Short Code description: >- URL alias to query stats for. **Required** when `scope=anon`. When `scope=all`, this is optional and filters stats to a specific URL. - name: start_date in: query required: false schema: anyOf: - type: string - 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 the URL creation 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 the URL creation date. - name: end_date in: query required: false schema: anyOf: - type: string - 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 - 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) - `country` — group by country - `city` — group by city - `referrer` — group by referrer URL - `short_code` — group by URL alias (only with `scope=all`) 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) - `country` — group by country - `city` — group by city - `referrer` — group by referrer URL - `short_code` — group by URL alias (only with `scope=all`) Multiple dimensions can be combined: `time,browser` returns time series broken down by browser. - name: metrics in: query required: false schema: anyOf: - type: string - 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 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 - 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) - `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) - `short_code` — Filter by URL alias (e.g., mylink, promo2024) — **not allowed** with `scope=anon` **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 - `{"short_code": ["link1", "link2"]}` — Stats for specific URLs (`scope=all` only) **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) - `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) - `short_code` — Filter by URL alias (e.g., mylink, promo2024) — **not allowed** with `scope=anon` **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 - `{"short_code": ["link1", "link2"]}` — Stats for specific URLs (`scope=all` only) **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 - 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 - 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: country in: query required: false schema: anyOf: - type: string - 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 - 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 - 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. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/StatsResponse' '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' security: - {} - ApiKeyAuth: [] - JWTAuth: [] components: schemas: StatsResponse: properties: scope: type: string title: Scope filters: additionalProperties: true 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 - 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' type: object required: - scope - filters - group_by - timezone - time_range - summary title: StatsResponse description: >- Response body for GET /api/v1/stats. ``metrics`` uses dynamic keys ({metric}_by_{dimension}), each mapping to a list of data-point dicts. Optional fields (``short_code``, ``time_bucket_info``, ``computed_metrics``) are absent when not applicable. ErrorResponse: properties: error: type: string title: Error error_code: type: string title: Error Code field: anyOf: - type: string - type: 'null' title: Field details: anyOf: - {} - type: 'null' title: Details type: object required: - error - 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 StatsTimeRange: properties: start_date: anyOf: - type: string - type: 'null' title: Start Date end_date: anyOf: - type: string - 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 - type: 'null' title: First Click last_click: anyOf: - type: string - type: 'null' title: Last Click avg_redirection_time: type: number title: Avg Redirection Time type: object required: - total_clicks - unique_clicks - avg_redirection_time 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 `' ````