Skip to main content
A short link hides where it leads. This source searches an index of shortened links by their destination URL, so you can find short links that lead to your domain, to a look-alike of it, or to files whose URL contains your brand. The flow is asynchronous: start a search, poll it until it ends, then read the links it collected. Availability: URL Shortener Abuse. Not every plan includes it. See Plans and quotas. Cost: no metered allowance. Plans that include URL Shortener Abuse do not limit how many searches you start. With an API key, each call that returns 2xx uses 1 unit of your monthly API Calls allowance, and a non-2xx response is refunded. Every submit, poll and read also counts toward the per-second rate limit. See Rate limits. Without the feature, or when your license is not active, the four search endpoints (create_, get_, list_ and delete_shortener_search_request) return 403:
1

Start the search

create_shortener_search_request takes your term as search_term.
The call returns 201 with the search:
Keep the id. A search you start here runs once. is_monitoring, alert_cycle and is_email are monitoring settings this endpoint does not set. is_reporting and report_id are filled only on searches that a report started.
2

Poll until it ends

Fetch the search with get_shortener_search_request until status is finished.
status is in_progress while the search runs and finished when it ends. There is no failed state: a search that hits an error in the shortener index also ends finished, with the links collected so far. Poll every 10 seconds or slower.
3

Read the links

list_shortener_search_result returns the links of one search. Pass the search id as searchrequest.

​
What a search collects

  • The term is matched against destination URLs in the shortener index. Space-separated words must all match, and a word with a - prefix excludes links that contain it: acme invoice -test.
  • At most 5,000 links per search. The search reads the index 1,000 links at a time and stops after five pages.
  • The submit options decide which 5,000. By default the newest discovered links come first (order timestamp, direction desc). extensions limits the search to destinations with those file extensions. The read options only filter and sort what was collected.
  • Every matching link is kept. No link is judged safe or malicious, so short links to your own site and documents match too. Drop them with exclude_domain when you read.
  • A search is a snapshot. It does not refresh. Start a new search to pick up links indexed since.

​
Submit parameters

​
Read parameters

​
What comes back

The read call returns one page of links plus counts for the whole search:
  • count — links that match your read filters, across all pages.
  • total_count — every link the search collected, before read filters.
  • available_extensions — every destination file extension in the search, for building an extension filter.
  • available_shortened_domains — every shortener host in the search, for building a shortened_domain filter.
  • next / previous — set while more pages exist. They point at an internal service, not at client-api.leak.center, so don’t call them. Page by raising page until next is null.
  • results — the links on this page.
available_extensions and available_shortened_domains ignore your read filters, like total_count. Each link carries:
  • shortener — the short URL itself.
  • shortener_hostname — the shortener service host.
  • link — the destination URL the short link leads to.
  • domain — the destination’s host.
  • extension — the destination’s file extension.
  • size — the destination file size in bytes, or null.
  • discovered_date — when the shortener index discovered the link, in UTC.
  • appeared_date — the date your search stored the link (YYYY-MM-DD). It is not the date the link was created.
  • id — the link’s ID, for the single-link and delete calls.
  • searchrequest — the search it belongs to.
Here exclude_domain=acme.com dropped one link to your own site, so count is 1 while total_count is 2. To fetch one link again, call get_shortener_search_result with its id.

​
Work with the results

  • Separate your own links from the rest. exclude_domain=acme.com drops every link whose URL contains acme.com anywhere. That includes links on other hosts that put acme.com in the path, such as http://login.example/acme.com/reset. To keep those, leave out exclude_domain and drop the rows whose domain is your own host on your side.
  • Look at files. available_extensions lists the file types in the search. Read one type with extension.
  • Follow a destination host. Search the destination domain in New domain registrations to see when it was registered, in SSL transparency logs to see its certificates, and in Phishing references to see whether phishing feeds list it.
To collect new links for a term without starting searches yourself, create a monitor on the Shortener service (10 in the service list) with {"search_term": "acme"} as args. It needs the same URL Shortener Abuse feature. See Create and manage monitors.

​
List and delete searches

list_shortener_search_request returns your organization’s searches, newest first.
  • page starts at 1. page_size defaults to 20, max 100.
  • ordering takes create_date, -create_date, update_date or -update_date. Default -create_date.
Both deletes return 204 and are permanent. Delete a search only after it is finished.

​
Errors

​
Endpoints