> ## 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 Statistics > Export URL click statistics as a downloadable file. Generate a file export of click analytics data in the specified format. The response is a binary download with appropriate `Content-Disposition` header. **Authentication**: Optional for `scope=anon` (public stats on a single URL); required for `scope=all`. **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: - Authenticated: 30/min, 1,000/day - Anonymous: 10/min, 200/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 **Note**: Export generation is resource-intensive. Lower rate limits apply compared to other endpoints. ## OpenAPI ````yaml /openapi-v1.json get /api/v1/export 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: get: tags: - Statistics summary: Export Statistics description: >- Export URL click statistics as a downloadable file. Generate a file export of click analytics data in the specified format. The response is a binary download with appropriate `Content-Disposition` header. **Authentication**: Optional for `scope=anon` (public stats on a single URL); required for `scope=all`. **API Key Scope**: `stats:read`, `urls:read`, or `admin:all` **Rate Limits**: - Authenticated: 30/min, 1,000/day - Anonymous: 10/min, 200/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 **Note**: Export generation is resource-intensive. Lower rate limits apply compared to other endpoints. operationId: exportStats 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. - name: format in: query required: true schema: enum: - csv - xlsx - json - xml type: string description: Export file format. title: Format description: Export file format. 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' security: - {} - ApiKeyAuth: [] - JWTAuth: [] components: schemas: 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 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 `' ````