URL Shortener API in Python: Create Links, Export Clicks

export SENDURL_API_KEY="snu_..."   # never commit it

import os

import requests

res = requests.post(
    "https://api.sendurl.to/api/v1/links",
    headers={"Authorization": f"Bearer {os.environ['SENDURL_API_KEY']}"},
    json={"destinationUrl": "https://example.com/autumn-sale"},
    timeout=10,
)
res.raise_for_status()
link = res.json()
print(link["shortUrl"], link["id"])

https://snu.to/x7Kp2 5d8f2a1c-7b3e-4c9d-a0e1-6f2b8c4d1e7a

{
  "id": "5d8f2a1c-7b3e-4c9d-a0e1-6f2b8c4d1e7a",
  "slug": "x7Kp2",
  "destinationUrl": "https://example.com/autumn-sale",
  "shortUrl": "https://snu.to/x7Kp2",
  "qrUrl": "https://snu.to/x7Kp2?q",
  "active": true,
  "expiresAt": null,
  "passwordProtected": false,
  "visitsLimit": 100000,
  "createdAt": "2026-10-13T09:12:44.123Z"
}

"""A small client for the SendURL REST API (https://sendurl.to/docs)."""
import os
import time

import requests

API = "https://api.sendurl.to/api/v1"
MIN_INTERVAL = 0.25  # 4 requests a second, under Cloudflare's 50 per 10 seconds

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SENDURL_API_KEY']}"
_last_request = 0.0


class SendURLError(Exception):
    """An error answer: `code` is the API's `error` field, e.g. "slug_taken"."""

    def __init__(self, status, body):
        super().__init__(f"{status} {body.get('error')}: {body.get('message')}")
        self.status = status
        self.code = body.get("error")
        self.body = body


def _pause():
    global _last_request
    wait = _last_request + MIN_INTERVAL - time.monotonic()
    if wait > 0:
        time.sleep(wait)
    _last_request = time.monotonic()


def _retry_after(res, attempt):
    try:
        return float(res.headers["Retry-After"])
    except (KeyError, ValueError):
        return 10 * (attempt + 1)


def call(method, path, attempts=5, **kwargs):
    """One API request. Returns the JSON body or raises SendURLError."""
    for attempt in range(attempts):
        _pause()
        res = session.request(method, f"{API}{path}", timeout=10, **kwargs)
        # 429 comes from Cloudflare before the API sees the request (so a retry
        # can't create a duplicate); 503 means the key couldn't be checked.
        if res.status_code in (429, 503) and attempt < attempts - 1:
            time.sleep(_retry_after(res, attempt))
            continue
        if res.ok:
            return res.json()
        try:
            body = res.json()
        except ValueError:  # not JSON: Cloudflare's 429 page, a proxy error
            body = {"error": f"http_{res.status_code}", "message": res.text[:200]}
        raise SendURLError(res.status_code, body)


def create_link(destination, slug=None, title=None, expires_at=None):
    body = {"destinationUrl": destination}
    if slug:
        body["slug"] = slug
    if title:
        body["title"] = title
    if expires_at:
        body["expiresAt"] = expires_at  # ISO 8601 with Z or an offset
    try:
        return call("POST", "/links", json=body)
    except SendURLError as e:
        # A random slug can (rarely) collide: send it again. A custom one can't be fixed here.
        if e.code == "slug_taken" and not slug:
            return call("POST", "/links", json=body)
        raise


def get_link(link_id):
    return call("GET", f"/links/{link_id}")


def pages(path, key, **params):
    """Every item of a list endpoint, following pagination.nextCursor."""
    cursor = None
    while True:
        query = {**params, "limit": 10}
        if cursor:
            query["cursor"] = cursor
        page = call("GET", path, params=query)
        yield from page[key]
        cursor = page["pagination"]["nextCursor"]
        if not cursor:
            return


def all_links(project_id=None):
    return pages("/links", "links", **({"projectId": project_id} if project_id else {}))


def all_clicks(link_id):
    return pages(f"/links/{link_id}/clicks", "clicks")


def find_link(slug):
    """The link with this slug in your workspace, or None. Slugs are case-sensitive."""
    return next((link for link in all_links() if link["slug"] == slug), None)

destination,slug,title
https://example.com/autumn-sale?utm_source=instagram&utm_medium=social&utm_campaign=2026-10-autumn-sale&utm_content=bio,autumn-sale-ig-bio,Autumn sale: Instagram bio
https://example.com/autumn-sale?utm_source=newsletter&utm_medium=email&utm_campaign=2026-10-autumn-sale,autumn-sale-email,Autumn sale: newsletter
https://example.com/autumn-sale?utm_source=poster&utm_medium=qr&utm_campaign=2026-10-autumn-sale&utm_content=window,,Autumn sale: shop window poster

import csv
import sys

from sendurl import SendURLError, create_link

with open(sys.argv[1], newline="") as src, open("created.csv", "w", newline="") as out:
    writer = csv.writer(out)
    writer.writerow(["slug", "short_url", "qr_url", "id", "destination", "error"])
    for row in csv.DictReader(src):
        try:
            link = create_link(row["destination"], slug=row.get("slug"), title=row.get("title"))
        except SendURLError as e:
            print(f"skipped {row.get('slug') or row['destination']}: {e}")
            writer.writerow([row.get("slug", ""), "", "", "", row["destination"], e.code])
            if e.code == "link_limit_reached":
                break  # every further row would fail the same way
            continue
        print(f"created {link['shortUrl']}")
        writer.writerow([link["slug"], link["shortUrl"], link["qrUrl"], link["id"], link["destinationUrl"], ""])

created https://snu.to/autumn-sale-ig-bio
created https://snu.to/autumn-sale-email
created https://snu.to/6I8dN

skipped autumn-sale-ig-bio: 409 slug_taken: That slug is already taken — try another.
skipped autumn-sale-email: 409 slug_taken: That slug is already taken — try another.
created https://snu.to/dYbqD

from sendurl import call, find_link

link = find_link("autumn-sale-ig-bio")
print(link["totalClicks"], "clicks")
print(call("GET", f"/links/{link['id']}")["qrScans"], "of them QR scans")
for day in call("GET", f"/links/{link['id']}/stats"):
    print(day["date"], day["count"])

{
  "id": "a4c6e8f0-1b3d-4e5f-9a7b-2c4d6e8f0a1b",
  "linkId": "5d8f2a1c-7b3e-4c9d-a0e1-6f2b8c4d1e7a",
  "clickedAt": "2026-10-14T08:03:11.482Z",
  "source": "qr",
  "country": "DE",
  "city": null,
  "referer": null,
  "ip": "203.0.113.24",
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) …",
  "device": "mobile",
  "deviceVendor": "Apple",
  "deviceModel": "iPhone",
  "browser": "Mobile Safari",
  "browserVersion": "18.6",
  "os": "iOS",
  "osVersion": "18.6"
}

"pagination": {
  "limit": 10,
  "nextCursor": "WyIyMDI2LTEwLTE0VDA4OjAzOjExLjQ4MjkxM1oiLCJhNGM2ZThmMC0xYjNkLTRlNWYtOWE3Yi0yYzRkNmU4ZjBhMWIiXQ",
  "hasMore": true
}

from sendurl import all_clicks, find_link

link = find_link("autumn-sale-ig-bio")
scans = sum(1 for click in all_clicks(link["id"]) if click["source"] == "qr")
print(f"{scans} QR scans out of {link['totalClicks']} clicks")

import csv
import sys

from sendurl import all_clicks, find_link

FIELDS = ["clickedAt", "source", "country", "device", "os", "browser", "referer", "userAgent", "id"]

slug = sys.argv[1]
link = find_link(slug)
if link is None:
    sys.exit(f"no link with the slug {slug} in this workspace")

path = f"{slug}-clicks.csv"
with open(path, "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=FIELDS, extrasaction="ignore")
    writer.writeheader()
    count = 0
    for click in all_clicks(link["id"]):
        writer.writerow(click)
        count += 1

print(f"{count} clicks written to {path} (totalClicks: {link['totalClicks']})")

25 clicks written to autumn-sale-ig-bio-clicks.csv (totalClicks: 25)

import sys

import pandas as pd

# keep_default_na=False: otherwise pandas reads Namibia's code "NA" as missing.
df = pd.read_csv(sys.argv[1], keep_default_na=False, na_values=[""])
df["clickedAt"] = pd.to_datetime(df["clickedAt"], utc=True, format="ISO8601")
df["via"] = df["source"].map({"qr": "QR scan"}).fillna("link")

print("Clicks per day (UTC)")
print(df.groupby(df["clickedAt"].dt.date).size().to_string(), "\n")
print("QR scans vs link clicks")
print(df["via"].value_counts().to_string(), "\n")
print("Top countries")
print(df["country"].fillna("unknown").value_counts().head(10).to_string(), "\n")
print("Devices")
print(df["device"].fillna("unknown").value_counts().to_string())

Clicks per day (UTC)
clickedAt
2026-10-14    25

QR scans vs link clicks
via
link       17
QR scan     8

Top countries
country
unknown    7
IN         5
DE         5
US         4
NA         4

Devices
device
mobile     15
unknown     7
desktop     3

// A small client for the SendURL REST API. Node 18+ (global fetch), no dependencies.
const API = "https://api.sendurl.to/api/v1";
const KEY = process.env.SENDURL_API_KEY;
if (!KEY) throw new Error("Set SENDURL_API_KEY first");

const MIN_INTERVAL_MS = 250; // 4 requests a second, under Cloudflare's 50 per 10 seconds
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let lastRequest = 0;

export class SendURLError extends Error {
  constructor(status, body) {
    super(`${status} ${body.error}: ${body.message}`);
    this.status = status;
    this.code = body.error; // e.g. "slug_taken"
    this.body = body;
  }
}

export async function call(method, path, { body, query = {}, attempts = 5 } = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(query)) if (v != null) url.searchParams.set(k, String(v));

  for (let attempt = 0; ; attempt++) {
    const wait = lastRequest + MIN_INTERVAL_MS - Date.now();
    if (wait > 0) await sleep(wait);
    lastRequest = Date.now();

    const res = await fetch(url, {
      method,
      headers: {
        Authorization: `Bearer ${KEY}`,
        ...(body && { "Content-Type": "application/json" }),
      },
      body: body && JSON.stringify(body),
      signal: AbortSignal.timeout(10_000),
    });
    // 429 is Cloudflare's (not JSON); 503 means the key couldn't be checked. Both are safe to retry.
    if ((res.status === 429 || res.status === 503) && attempt < attempts - 1) {
      const retryAfter = Number(res.headers.get("retry-after"));
      await sleep((retryAfter > 0 ? retryAfter : 10 * (attempt + 1)) * 1000);
      continue;
    }
    const text = await res.text();
    if (res.ok) return JSON.parse(text);
    let err;
    try {
      err = JSON.parse(text);
    } catch {
      err = { error: `http_${res.status}`, message: text.slice(0, 200) };
    }
    throw new SendURLError(res.status, err);
  }
}

export async function createLink({ destinationUrl, slug, title, expiresAt }) {
  const body = { destinationUrl, ...(slug && { slug }), ...(title && { title }), ...(expiresAt && { expiresAt }) };
  try {
    return await call("POST", "/links", { body });
  } catch (e) {
    // A random slug can (rarely) collide: send it again. A custom one can't be fixed here.
    if (e.code === "slug_taken" && !slug) return call("POST", "/links", { body });
    throw e;
  }
}

/** Every item of a list endpoint, following pagination.nextCursor. */
export async function* pages(path, key, query = {}) {
  let cursor;
  do {
    const page = await call("GET", path, { query: { ...query, limit: 10, cursor } });
    yield* page[key];
    cursor = page.pagination.nextCursor;
  } while (cursor);
}

export const allLinks = (projectId) => pages("/links", "links", { projectId });
export const allClicks = (linkId) => pages(`/links/${linkId}/clicks`, "clicks");

/** The link with this slug in your workspace, or null. Slugs are case-sensitive. */
export async function findLink(slug) {
  for await (const link of allLinks()) if (link.slug === slug) return link;
  return null;
}

// Minimal CSV helpers: quoted fields, "" escapes, CRLF or LF line ends.
export function parseCsv(text) {
  const rows = [];
  let row = [], field = "", quoted = false;
  for (let i = 0; i < text.length; i++) {
    const c = text[i];
    if (quoted) {
      if (c === '"' && text[i + 1] === '"') { field += '"'; i++; }
      else if (c === '"') quoted = false;
      else field += c;
    } else if (c === '"') quoted = true;
    else if (c === ",") { row.push(field); field = ""; }
    else if (c === "\n" || c === "\r") {
      if (c === "\r" && text[i + 1] === "\n") i++;
      row.push(field); rows.push(row); row = []; field = "";
    } else field += c;
  }
  if (field || row.length) { row.push(field); rows.push(row); }
  const [header, ...data] = rows.filter((r) => r.some((f) => f !== ""));
  return data.map((r) => Object.fromEntries(header.map((h, i) => [h, r[i] ?? ""])));
}

export function toCsvLine(values) {
  return values
    .map((v) => {
      const s = v == null ? "" : String(v);
      return /[",\r\n]/.test(s) ? `"${s.replaceAll('"', '""')}"` : s;
    })
    .join(",") + "\n";
}

// node bulk-create.mjs links.csv  →  created.csv
import { readFileSync, writeFileSync } from "node:fs";
import { createLink, SendURLError } from "./sendurl.mjs";
import { parseCsv, toCsvLine } from "./csv.mjs";

let out = toCsvLine(["slug", "short_url", "qr_url", "id", "destination", "error"]);
for (const row of parseCsv(readFileSync(process.argv[2], "utf8"))) {
  try {
    const link = await createLink({ destinationUrl: row.destination, slug: row.slug, title: row.title });
    console.log(`created ${link.shortUrl}`);
    out += toCsvLine([link.slug, link.shortUrl, link.qrUrl, link.id, link.destinationUrl, ""]);
  } catch (e) {
    if (!(e instanceof SendURLError)) throw e;
    console.log(`skipped ${row.slug || row.destination}: ${e.message}`);
    out += toCsvLine([row.slug, "", "", "", row.destination, e.code]);
    if (e.code === "link_limit_reached") break;
  }
}
writeFileSync("created.csv", out);

// node export-clicks.mjs autumn-sale-ig-bio  →  autumn-sale-ig-bio-clicks.csv
import { writeFileSync } from "node:fs";
import { allClicks, findLink } from "./sendurl.mjs";
import { toCsvLine } from "./csv.mjs";

const FIELDS = ["clickedAt", "source", "country", "device", "os", "browser", "referer", "userAgent", "id"];
const slug = process.argv[2];
const link = await findLink(slug);
if (!link) {
  console.error(`no link with the slug ${slug} in this workspace`);
  process.exit(1);
}

let out = toCsvLine(FIELDS);
let count = 0;
for await (const click of allClicks(link.id)) {
  out += toCsvLine(FIELDS.map((f) => click[f]));
  count++;
}
writeFileSync(`${slug}-clicks.csv`, out);
console.log(`${count} clicks written to ${slug}-clicks.csv (totalClicks: ${link.totalClicks})`);

node bulk-create.mjs links.csv
node export-clicks.mjs autumn-sale-ig-bio

{
  "error": "validation_error",
  "message": "Invalid request",
  "issues": [
    { "code": "custom", "message": "That slug is reserved", "path": ["slug"] }
  ]
}