> ## 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. # Export Link Statistics > Export click statistics for a single URL you own. The export twin of `GET /stats/links/{url_id}` — the same formats as `GET /export`, pre-scoped to one link. The suggested filename carries the link's alias. **Authentication**: Required — you must own the URL. **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: 30/min, 1,000/day **Export Formats**: - `json` — single JSON file - `xml` — single XML file - `xlsx` — Excel spreadsheet with multiple sheets - `csv` — **ZIP archive** containing `summary.csv` plus one CSV file per metrics dimension **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. **Note**: Export generation is resource-intensive. Lower rate limits apply compared to other endpoints. ## OpenAPI ````yaml /openapi-v1.json get /api/v1/export/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/export/links/{url_id}: get: tags: - Statistics summary: Export Link Statistics description: >- Export click statistics for a single URL you own. The export twin of `GET /stats/links/{url_id}` — the same formats as `GET /export`, pre-scoped to one link. The suggested filename carries the link's alias. **Authentication**: Required — you must own the URL. **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: 30/min, 1,000/day **Export Formats**: - `json` — single JSON file - `xml` — single XML file - `xlsx` — Excel spreadsheet with multiple sheets - `csv` — **ZIP archive** containing `summary.csv` plus one CSV file per metrics dimension **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. **Note**: Export generation is resource-intensive. Lower rate limits apply compared to other endpoints. operationId: exportLinkStats 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: format in: query required: true schema: enum: - csv - xlsx - json - xml type: string description: Export file format. title: Format description: Export file format. - 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: Export file download content: application/json: schema: type: string format: binary application/xml: schema: type: string format: binary application/zip: schema: type: string format: binary x-description: >- CSV export — ZIP archive containing summary.csv plus one file per dimension application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary x-description: XLSX export — Excel workbook with multiple sheets '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' '500': description: Internal server error — export generation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: 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 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 `' ````