Skip to main content
GET
/
stats
URL Statistics
curl --request GET \
  --url https://spoo.me/api/v1/stats \
  --header 'Authorization: Bearer <token>'
{
  "scope": "all",
  "timezone": "America/New_York",
  "group_by": [
    "<string>"
  ],
  "filters": {},
  "time_range": {
    "start_date": "2023-11-07T05:31:56Z",
    "end_date": "2023-11-07T05:31:56Z"
  },
  "summary": {
    "total_clicks": 123,
    "unique_clicks": 123,
    "first_click": "2023-11-07T05:31:56Z",
    "last_click": "2023-11-07T05:31:56Z",
    "avg_redirection_time": 123
  },
  "metrics": {}
}

Authorizations

​
Authorization
string
header
required

API key in format: spoo_. Use in Authorization header as 'Bearer spoo_'

Query Parameters

​
scope
enum<string>
required

Statistics scope: 'all' (authenticated only) or 'anon' (public access)

Available options:
all,
anon
​
short_code
string

URL alias (required when scope=anon)

​
start_date
string

ISO 8601 datetime or Unix timestamp (default: 7 days ago)

​
end_date
string

ISO 8601 datetime or Unix timestamp (default: now)

​
timezone
string
default:UTC

IANA timezone for output formatting (default: UTC)

​
group_by
string
default:time

Comma-separated dimensions: time, browser, os, country, city, referrer, short_code

​
metrics
string
default:clicks,unique_clicks

Comma-separated metrics: clicks, unique_clicks

​
filters
string

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 code (e.g., US, CA, GB, IN)
  • 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"]} - Filter for Chrome OR Firefox clicks
  • {"country": ["US", "CA"], "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, short_code parameters below)

​
browser
string

Method 2: Individual Filter Parameter

Comma-separated browser names. Alternative to using the filters JSON parameter.

Format: Comma-separated string (e.g., Chrome,Firefox,Safari)

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.

​
os
string

Method 2: Individual Filter Parameter

Comma-separated operating system names. Alternative to using the filters JSON parameter.

Format: Comma-separated string (e.g., Windows,macOS,Linux)

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.

​
country
string

Method 2: Individual Filter Parameter

Comma-separated ISO 3166-1 alpha-2 country codes. Alternative to using the filters JSON parameter.

Format: Comma-separated string (e.g., US,CA,GB)

Important: Values are case-sensitive. Use uppercase two-letter codes:

  • US (United States)
  • CA (Canada)
  • GB (United Kingdom)
  • IN (India)
  • AU (Australia)
  • DE (Germany)
  • FR (France)
  • JP (Japan)

Note: Both filters JSON and individual parameters can be combined.

​
city
string

Method 2: Individual Filter Parameter

Comma-separated city names. Alternative to using the filters JSON parameter.

Format: Comma-separated string (e.g., New York,London,Mumbai)

Important: Values are case-sensitive. Use exact capitalization as stored in the database.

Note: Both filters JSON and individual parameters can be combined.

​
referrer
string

Method 2: Individual Filter Parameter

Comma-separated referrer URLs. Alternative to using the filters JSON parameter.

Format: Comma-separated string of full URLs (e.g., https://google.com,https://twitter.com)

Important: Values are case-sensitive. Include the full URL including protocol.

Note: Both filters JSON and individual parameters can be combined.

Response

Statistics retrieved successfully

​
scope
enum<string>
Available options:
all,
anon
​
timezone
string
Example:

"America/New_York"

​
group_by
string[]
​
filters
object
​
time_range
object
​
summary
object
​
metrics
object

Grouped statistics based on group_by parameter