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
- You send the link to
POST /v1/traces, with your key. - A real Chrome opens it and follows every redirect: HTTP, meta refresh, JavaScript and forms. The trace ends once nothing has changed for
idleTimeseconds. - 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.
X-Billing-Token: YOUR_KEYNote: 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
https://trace.unshortlink.com/v1/tracesSend 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
| Name | Type | Default | Description |
|---|---|---|---|
urlRequired | string | Required— | The link to trace, http or https. Without a scheme, https:// is added. |
device | string | Default desktop | What the browser presents itself as: desktop, iphone or android. |
headers | object | Default {} | Extra headers for every request in the chain, such as Accept-Language. Every site in the chain gets them, so no secrets. |
maxRedirects | integer | Default 20 | Stops the trace after this many redirects, from 1 to 20. |
timeLimit | integer | Default 50 | The longest the call may take, in seconds, from 5 to 50. |
idleTime | integer | Default 3 | Seconds without a change before the trace ends, from 3 to 30. Raise it for pages that redirect late. |
body | boolean | Default false | Adds 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:
{
"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:
| Field | What it holds |
|---|---|
id | The trace's id |
url | The link as traced, with https:// added when it had no scheme |
startedAt, finishedAt, durationMs | When the trace started and ended, and how long it took in milliseconds |
settled | What ended the trace: stable, time_limit or redirect_limit |
redirects | How many redirects, and who made them: the server, the page or Chrome |
end | What the link ended in: a page, a download, an app, an error… See how a link can end. |
final | The last page: its address, the address without tracking parameters, its status and title |
steps | Every step: its address, status code, how it redirected, the server, its certificate, timings, headers and cookies |
page | The final page: description, language, Open Graph tags, technology, a text sample… |
domains | Each domain in the chain: when it was registered and expires, its registrar and its status, from the registry |
certificate | The final page's certificate: issuer, verified company, validity |
safety | Safe Browsing, the route through each host, the tracking parameters removed |
downloads, file | Files the link started or showed, with their fingerprints |
downloadsRefused | How many files the link started after the first 5: they were stopped before they began |
lookups | Links to VirusTotal, urlscan and the Wayback Machine for the final domain |
report | When the result and its files are deleted, 30 days later |
request | The options the trace used, defaults included |
meta | The 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:
| Ending | What it means | Comes with |
|---|---|---|
page | A web page. | Comes with: Nothing more. |
download | The link started a download. | Comes with: end.files, the downloads list and downloadsRefused. |
file | A file the browser showed itself, such as a PDF or an image. | Comes with: The file object: its name, size, fingerprints and real type. |
app | An 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_error | The last answer was an HTTP error (400 or above). | Comes with: end.status. |
empty | The last answer had no content (204 or 205). | Comes with: end.status. |
network_error | Nothing 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_check | A bot check stopped the browser. | Comes with: end.botCheck: the provider (Cloudflare, DataDome, Imperva…). |
warning_page | Chrome 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. |
redirect | The 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.
{
"error": {
"code": "invalid_request",
"message": "url is required.",
"param": "url"
}
}| Status | Code | When |
|---|---|---|
400 | invalid_request | Malformed JSON, an unknown parameter or a value out of range. param names it. |
403 | forbidden_url | A private, local or reserved address, or a link our abuse rules refuse. |
403 | — | A missing or wrong key. Nadles answers it, with its own message body. Copy your key again from the portal. |
413 | request_too_large | A body over 64 KB. |
429 | — | Your plan's traces are used up, or you called faster than its rate limit. |
500 | internal_error | Our fault. Try again. |
503 | busy | No browser was free in time. Try again. |
503 | unavailable | The API is paused. Try again later. |
Note: A call counts as one trace only when it answers 200.
Limits and quotas
| Limit | Value |
|---|---|
| Traces a month | Your plan's quota. Only 200 answers count. See how many are left in the portal. |
| Calls a second | Set by your plan. Faster calls get 429. |
| Time per call | 50 seconds at most, set with timeLimit. |
| Redirects | 20 per trace at most, set with maxRedirects. |
| Request body | 64 KB at most. |
| Page bodies | 200 KB each, with body: true. |
| Results kept | 30 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.
Get your key
Pick a monthly plan. Nadles takes the payment and gives you a key.
See the plans