Statistics

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.

GET

api

export

links

{url_id}

Export Link Statistics

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

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

fetch('https://spoo.me/api/v1/export/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/export/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/export/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/export/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

"<string>"

{
  "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
}

{
  "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

format

enum<string>

required

Export file format.

Available options:

csv,

xlsx,

json,

xml

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

Export file download

The response is of type file.

Export Link Statistics

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

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

fetch('https://spoo.me/api/v1/export/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/export/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/export/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/export/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

"<string>"

{
  "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
}

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

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Export Link Statistics

Authorizations

Path Parameters

Query Parameters

Response