API documentation

How to trace links from your code: the request, the answer, errors and limits.

Introduction

The Redirect Trace API opens a link in a real Chrome on our servers, follows every redirect to the end and answers with one JSON document: each step with its status code, how it redirected, and the page it ended on.

How a call works

  1. You send the link to POST /v1/traces, with your key.
  2. A real Chrome opens it and follows every redirect: HTTP, meta refresh, JavaScript and forms. The trace ends once nothing has changed for idleTime seconds.
  3. The call answers with the whole chain in one JSON document.

Note: The call stays open until the trace ends: at most timeLimit seconds, 50 by default. Set your HTTP client's timeout to 60 seconds.

Authentication

Send your key in the X-Billing-Token header of every call. You get it when you subscribe to a plan: it's in your account on portal.unshortlink.com, where you can also see this month's usage, change or cancel your plan, and download your invoices.

Header
X-Billing-Token: YOUR_KEY

Note: Keep the key on your server, never in a web page or an app: anyone who has it can use your plan's traces. A call without a valid key gets 403.

The request

POSThttps://trace.unshortlink.com/v1/traces

Send a JSON body with the Content-Type: application/json header. Only url is required. A parameter we don't know is refused with 400, so a typo fails loudly instead of being ignored.

Parameters

urlstringRequiredThe link to trace, http or https. Without a scheme, https:// is added.
devicestringDefault desktopWhat the browser presents itself as: desktop, iphone or android.
headersobjectDefault {}Extra headers for every request in the chain, such as Accept-Language. Every site in the chain gets them, so no secrets.
maxRedirectsintegerDefault 20Stops the trace after this many redirects, from 1 to 20.
timeLimitintegerDefault 50The longest the call may take, in seconds, from 5 to 50.
idleTimeintegerDefault 3Seconds without a change before the trace ends, from 3 to 30. Raise it for pages that redirect late.
bodybooleanDefault falseAdds every page's body, up to 200 KB each.

Example

Trace a link as an iPhone would open it:

curl -X POST https://trace.unshortlink.com/v1/traces \
  -H "X-Billing-Token: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/go",
    "device": "iphone"
  }'

The answer, shortened:

200 OK · application/json
{
  "id": "tr_7d1f0c9a2b8e4c51a3f6e0b9d2c4a817",
  "url": "https://example.com/go",
  "durationMs": 4210,
  "settled": "stable",
  "redirects": {
    "total": 2,
    "byServer": 2,
    "byPage": 0,
    "byChrome": 0
  },
  "end": { "type": "page", "step": 2 },
  "final": {
    "url": "https://shop.example.com/",
    "cleanUrl": "https://shop.example.com/",
    "status": 200,
    "title": "Summer sale"
  },
  "steps": [
    {
      "index": 0,
      "url": "https://example.com/go",
      "status": 301,
      "redirect": {
        "to": "https://www.example.com/go",
        "mechanism": "http"
      }
    },
    …
  ],
  "page": { … },
  "certificate": { … },
  "safety": { … }
}

The answer

A 200 answer holds the whole trace. Its main parts:

idThe trace's id
urlThe link as traced, with https:// added when it had no scheme
startedAt, finishedAt, durationMsWhen the trace started and ended, and how long it took in milliseconds
settledWhat ended the trace: stable, time_limit or redirect_limit
redirectsHow many redirects, and who made them: the server, the page or Chrome
endWhat the link ended in: a page, a download, an app, an error… See how a link can end.
finalThe last page: its address, the address without tracking parameters, its status and title
stepsEvery step: its address, status code, how it redirected, the server, its certificate, timings, headers and cookies
pageThe final page: description, language, Open Graph tags, technology, a text sample…
domainsEach domain in the chain: when it was registered and expires, its registrar and its status, from the registry
certificateThe final page's certificate: issuer, verified company, validity
safetySafe Browsing, the route through each host, the tracking parameters removed
downloads, fileFiles the link started or showed, with their fingerprints
downloadsRefusedHow many files the link started after the first 5: they were stopped before they began
lookupsLinks to VirusTotal, urlscan and the Wayback Machine for the final domain
reportWhen the result and its files are deleted, 30 days later
requestThe options the trace used, defaults included
metaThe API's version and when the answer was made

Every field is described in the OpenAPI file.

How a link can end

Every answer has the same parts, but end.type says how the link ended, and some fields come only with some endings:

pageA web page.Comes with: Nothing more.
downloadThe link started a download.Comes with: end.files, the downloads list and downloadsRefused.
fileA file the browser showed itself, such as a PDF or an image.Comes with: The file object: its name, size, fingerprints and real type.
appAn app link (WhatsApp, Telegram, App Store…).Comes with: end.app: the scheme, the app's name, the full link and, when known, the Android package, the App Store id and the fallback page.
http_errorThe last answer was an HTTP error (400 or above).Comes with: end.status.
emptyThe last answer had no content (204 or 205).Comes with: end.status.
network_errorNothing answered: the name doesn't resolve, the connection failed…Comes with: end.error (its kind and Chrome's message) and, when the name doesn't resolve, end.deadReason: why, from the registry (expired, suspended…).
bot_checkA bot check stopped the browser.Comes with: end.botCheck: the provider (Cloudflare, DataDome, Imperva…).
warning_pageChrome showed its own warning instead of the page.Comes with: end.warning (today always safe_browsing), end.threat (phishing, malware, unwanted_software, billing or unknown) and end.warningText, Chrome's own words.
redirectThe trace stopped at maxRedirects: the last step's redirect wasn't followed.Comes with: Nothing more.

Note: page is null when the link ended without a web page, certificate when the final page isn't secure (or there's none), and lookups for a page at a platform's own address, such as a Google Form.

Errors

An error answers with an HTTP status and a JSON body: a code your code can test, a message for a person and, for invalid_request, the param at fault.

400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "url is required.",
    "param": "url"
  }
}
400invalid_requestMalformed JSON, an unknown parameter or a value out of range. param names it.
403forbidden_urlA private, local or reserved address, or a link our abuse rules refuse.
403A missing or wrong key. Nadles answers it, with its own message body. Copy your key again from the portal.
413request_too_largeA body over 64 KB.
429Your plan's traces are used up, or you called faster than its rate limit.
500internal_errorOur fault. Try again.
503busyNo browser was free in time. Try again.
503unavailableThe API is paused. Try again later.

Note: A call counts as one trace only when it answers 200.

Limits and quotas

Traces a monthYour plan's quota. Only 200 answers count. See how many are left in the portal.
Calls a secondSet by your plan. Faster calls get 429.
Time per call50 seconds at most, set with timeLimit.
Redirects20 per trace at most, set with maxRedirects.
Request body64 KB at most.
Page bodies200 KB each, with body: true.
Results kept30 days, screenshots and file links included.

OpenAPI file

The whole API in one OpenAPI file: import it into Postman or Insomnia, or generate a client in your language.

Download openapi.json

Get your key

Pick a monthly plan. Nadles takes the payment and gives you a key.

See the plans