ข้ามไปยังเนื้อหา
Docs menu

Guides

URL shortener API in Python and JavaScript, bulk links from CSV and click export

Shorten URLs from Python and JavaScript with the Shortener.dev REST API. Create one link, create hundreds from a CSV within the rate limit, handle errors, and export every click to CSV.

Updated

This guide builds on Shorten URLs with the API with complete scripts for the jobs people usually automate: creating links in bulk from a spreadsheet, and getting click data back out. You need an API key, available on paid plans. The scripts read it from the SHORTENER_API_KEY environment variable.

export SHORTENER_API_KEY="your-key"
pip install requests
import os
import requests

API = "https://api.shortener.dev/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SHORTENER_API_KEY']}"

response = session.post(f"{API}/links", json={
    "url": "https://example.com/blog/spring-launch",
    "key": "spring-launch",
    "params": {"utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "spring_launch"},
})
if not response.ok:
    raise SystemExit(f"{response.status_code}: {response.json().get('message')}")

print(response.json()["short_url"])  # https://srt1.link/spring-launch

Leave out key to get a random back-half. Every option in the dashboard, such as expire_at, password, geo or project_id, is a field on the same request. The API reference lists them all.

Start with a CSV that has a url column, and optionally key, utm_source, utm_medium and utm_campaign:

url,key,utm_source,utm_medium,utm_campaign
https://example.com/shoes/trail-runner,trail-runner,instagram,social,2026_11_launch
https://example.com/shoes/road-racer,road-racer,instagram,social,2026_11_launch
https://example.com/shoes/kids-sprint,,newsletter,email,2026_11_launch

The script below creates a link for each row and writes the result, or the error, to a new CSV. It stays under the API's rate limit of 150 requests a minute and waits when it gets a 429 anyway:

import csv
import os
import sys
import time

import requests

API = "https://api.shortener.dev/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SHORTENER_API_KEY']}"

def create_link(row):
    body = {"url": row["url"].strip()}
    if row.get("key"):
        body["key"] = row["key"].strip()
    params = {k: row[k] for k in ("utm_source", "utm_medium", "utm_campaign") if row.get(k)}
    if params:
        body["params"] = params

    for attempt in range(5):
        response = session.post(f"{API}/links", json=body, timeout=30)
        if response.status_code == 429:
            time.sleep(15 * (attempt + 1))
            continue
        return response
    return response

source, target = sys.argv[1], sys.argv[2]
with open(source, newline="") as f_in, open(target, "w", newline="") as f_out:
    rows = csv.DictReader(f_in)
    writer = csv.DictWriter(f_out, fieldnames=[*rows.fieldnames, "short_url", "error"])
    writer.writeheader()
    for row in rows:
        response = create_link(row)
        if response.ok:
            row["short_url"] = response.json()["short_url"]
        else:
            row["error"] = f"{response.status_code}: {response.json().get('message')}"
            if response.status_code in (401, 402):
                writer.writerow(row)
                raise SystemExit(row["error"])  # bad key or link limit, stop here
        writer.writerow(row)
        time.sleep(0.5)  # about 120 requests a minute

Run it with python bulk_shorten.py links.csv links-short.csv. Rows that fail, for example because a back-half is taken, get the error message in the error column and the script carries on, so you can fix those rows and run them again.

Check your plan's link limit before a large run. The script stops on 402, which means the limit is reached. See Plans and limits.

The same in JavaScript

Node 18 and newer has fetch built in. This version reads URLs from a text file, one per line:

import { readFile } from 'node:fs/promises';

const API = 'https://api.shortener.dev/v1';
const headers = {
  Authorization: `Bearer ${process.env.SHORTENER_API_KEY}`,
  'Content-Type': 'application/json',
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function createLink(url, attempt = 0) {
  const response = await fetch(`${API}/links`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ url }),
  });
  if (response.status === 429 && attempt < 5) {
    await sleep(15000 * (attempt + 1));
    return createLink(url, attempt + 1);
  }
  const body = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${body.message}`);
  return body.short_url;
}

const urls = (await readFile(process.argv[2], 'utf8')).split('\n').map((line) => line.trim()).filter(Boolean);
for (const url of urls) {
  try {
    console.log(`${url},${await createLink(url)}`);
  } catch (error) {
    console.error(`${url},${error.message}`);
  }
  await sleep(500);
}

Save it as shorten.mjs and run node shorten.mjs urls.txt > links.csv.

Export clicks to CSV

GET /v1/reports returns the click log for the last 30 days, newest first, up to 1,000 clicks per request. Page through it with offset until you have every click:

import csv
import os

import requests

API = "https://api.shortener.dev/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SHORTENER_API_KEY']}"

fields = ["timestamp", "url", "country", "region", "city", "referer", "browser", "os", "device", "ip"]
with open("clicks.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=fields, extrasaction="ignore")
    writer.writeheader()
    offset = 0
    while True:
        response = session.get(f"{API}/reports", params={"offset": offset, "limit": 1000}, timeout=60)
        response.raise_for_status()
        page = response.json()
        writer.writerows(page["result"])
        offset += page["returned"]
        if page["returned"] == 0 or offset >= page["total"]:
            break

print(f"Saved {offset} clicks to clicks.csv")

The endpoint also takes country, city, referer, browser, os and device filters, for example params={"device": "mobile", ...} to export only mobile clicks. Clicks are stored in UTC.

For a quick number per link, GET /v1/analytics/clicks returns the last 30 days of clicks for up to 25 back-halves in one request:

response = session.get(f"{API}/analytics/clicks", params={"key": ["trail-runner", "road-racer", "kids-sprint"]})
for row in response.json():
    print(row["key"], row["clicks"])

requests repeats the key parameter for each value in the list, which is the format the endpoint expects.

Errors to handle

StatusWhen it happensWhat to do
400Invalid URL, a back-half that's taken, or an invalid fieldRead message, fix the row and retry it
401Missing or wrong API keyCheck SHORTENER_API_KEY
402Your plan's link limit is reachedStop, upgrade or wait for the monthly count to reset
403The destination domain isn't verifiedVerify the domain or use a whitelisted site
429More than 150 requests a minuteWait and retry, as the scripts above do

Frequently asked questions

Is there a free URL shortener API?

API access is included on the Starter plan and above. On the Free plan, create links in the dashboard or with the Bulk URL Shortener, which takes up to 50 URLs at once.

What's the API rate limit?

150 requests a minute. The scripts in this guide pause between requests and back off when they get a 429.

Can I set a custom back-half and UTM parameters in the same request?

Yes. Send key for the back-half and params for the UTM parameters, as in the first example.