Statistics

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.

GET

api

stats

links

{url_id}

Link Statistics

curl --request GET \
  --url https://spoo.me/api/v1/stats/links/{url_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://spoo.me/api/v1/stats/links/{url_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://spoo.me/api/v1/stats/links/{url_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://spoo.me/api/v1/stats/links/{url_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://spoo.me/api/v1/stats/links/{url_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "filters": {},
  "group_by": [
    "<string>"
  ],
  "timezone": "<string>",
  "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
  },
  "url_id": "<string>",
  "alias": "<string>",
  "metrics": {},
  "generated_at": "2023-11-07T05:31:56Z",
  "api_version": "<string>",
  "short_code": "<string>",
  "time_bucket_info": {
    "strategy": "<string>",
    "mongo_format": "<string>",
    "display_format": "<string>",
    "timezone": "<string>",
    "interval_minutes": 123
  },
  "computed_metrics": {
    "unique_click_rate": 123,
    "repeat_click_rate": 123,
    "average_clicks_per_visitor": 123
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

Authorizations

Authorization

string

header

required

API key authentication. Pass your key as: Bearer spoo_<your_key>

Path Parameters

url_id

string

required

Unique identifier of the URL (MongoDB ObjectId).

Query Parameters

start_date

string | null

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.

Maximum string length: 50

Example:

"2025-01-01T00:00:00Z"

end_date

string | null

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.

Maximum string length: 50

Example:

"2025-12-31T23:59:59Z"

group_by

string | null

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.

Maximum string length: 200

Example:

"time,browser"

metrics

string | null

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)

Maximum string length: 200

Example:

"clicks,unique_clicks"

timezone

string

default:UTC

IANA timezone name for time-based grouping and output formatting (e.g., UTC, America/New_York, Asia/Kolkata). Defaults to UTC.

Maximum string length: 50

Examples:

"UTC"

"America/New_York"

filters

string | null

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).

Maximum string length: 5000

Example:

"{\"browser\":[\"Chrome\",\"Firefox\"]}"

browser

string | null

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.

Maximum string length: 500

Example:

"Chrome,Firefox"

string | null

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.

Maximum string length: 500

Example:

"Windows,macOS"

device

string | null

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.

Maximum string length: 200

Example:

"mobile,desktop"

country

string | null

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.

Maximum string length: 1000

Example:

"United States,Germany"

city

string | null

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.

Maximum string length: 1000

Example:

"San Francisco,Berlin"

referrer

string | null

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.

Maximum string length: 2000

Example:

"https://google.com,https://twitter.com"

utm_source

string | null

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.

Maximum string length: 1000

Example:

"newsletter,twitter"

utm_medium

string | null

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.

Maximum string length: 1000

Example:

"email,social"

utm_campaign

string | null

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.

Maximum string length: 1000

Example:

"summer-launch"

Response

Successful Response

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.

scope

enum<string>

required

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.

Available options:

all,

anon

filters

Filters · object

required

Show child attributes

group_by

string[]

required

timezone

string

required

time_range

StatsTimeRange · object

required

Time range metadata inside StatsResponse.

Show child attributes

summary

StatsSummary · object

required

Summary statistics block inside StatsResponse.

Show child attributes

url_id

string

required

alias

string

required

metrics

Metrics · object

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'.

Show child attributes

generated_at

string<date-time> | null

api_version

string | null

short_code

string | null

time_bucket_info

TimeBucketInfo · object | null

Time bucketing metadata — only present when 'time' is in group_by.

Show child attributes

computed_metrics

ComputedMetrics · object | null

Optional computed metrics added by format_stats_response_with_metadata.

Show child attributes

Link Statistics

curl --request GET \
  --url https://spoo.me/api/v1/stats/links/{url_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://spoo.me/api/v1/stats/links/{url_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://spoo.me/api/v1/stats/links/{url_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://spoo.me/api/v1/stats/links/{url_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://spoo.me/api/v1/stats/links/{url_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "filters": {},
  "group_by": [
    "<string>"
  ],
  "timezone": "<string>",
  "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
  },
  "url_id": "<string>",
  "alias": "<string>",
  "metrics": {},
  "generated_at": "2023-11-07T05:31:56Z",
  "api_version": "<string>",
  "short_code": "<string>",
  "time_bucket_info": {
    "strategy": "<string>",
    "mongo_format": "<string>",
    "display_format": "<string>",
    "timezone": "<string>",
    "interval_minutes": 123
  },
  "computed_metrics": {
    "unique_click_rate": 123,
    "repeat_click_rate": 123,
    "average_clicks_per_visitor": 123
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "field": "<string>",
  "details": null
}

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Link Statistics

Authorizations

Path Parameters

Query Parameters

Response