Skip to main content
A quick search sends one term to every data source that covers it. A domain reaches 12 sources, an email address 8 and a password 4. You make one call and get back one search record, with one entry per source in its result. Sources that answer at once put their findings straight into the record. The others start a background job: you follow the job, then read its findings from that source’s own endpoint. In the dashboard, the same search is Search → Unified Search. Availability: every plan with a license in force. Each source also needs its plan feature. A source your plan does not include reports not_entitled in the record instead of findings. See What each search covers. Cost: no metered allowance. The search and each poll are one API call each. With an API key, a call that returns 2xx counts toward your monthly API Calls allowance, and any other status is refunded. The sources the search fans out to do not count against your API Calls allowance. Rate limits explains both limits. Besides a missing or invalid API key (401) and a malformed request (400), listed under Errors, the search and poll endpoints refuse a call in two ways: Plan features never refuse the search itself. They show up per source, inside result. Errors lists every error body.

Pick the search for your term

Each endpoint takes a JSON body with one search_term. Pick the endpoint that matches what the term is. A file name search also takes file_extension, such as csv, pdf or sql. Send it with every file name search: Leaks, Pastes Live Search and Open Cloud Storage build their query from the name and the extension together.

What each search covers

The term type decides which sources run. A ✓ means that search reaches that source. Source names are the names the record returns in feature_names. A card search reaches Leaks only when the term contains 16 digits in a row. Each source either answers inline or starts a background job, and each needs a plan feature or is included in every plan. The same sources are searchable one at a time in Expert Search, some under another name. Plans and quotas lists which plans include each feature.

How a quick search runs

1

Submit the term

POST your term to the matching endpoint. The platform calls every source in parallel and answers once each one has returned findings or started its job, so allow the call several seconds. It returns 201 with the search record.
2

Read the inline findings

Every inline source is done by the time the 201 arrives. Its entry has status: "ok" and its findings in data.
3

Follow each background job

Poll the record by its id to update the status of each job. Credentials is the exception: the record does not update it, so check it on its own endpoint.
4

Read each job's findings

Polling updates only status. When a job is done, read its findings from the source’s results endpoint, using the entry’s task_id.

The search record

This record from a domain search is trimmed to five sources, and each entry is shortened:
Every entry has a status, plus one of these:
  • data: the source’s findings, when it answered inline.
  • task_id: the id of the source’s background job. Most job entries also repeat the job’s own fields and the parameters sent to the source.
  • error_message: why the source did not run. A submission_failed entry usually adds service_status_code. When the leak or account index rejects the query, for example for a wildcard it does not support, error_message carries its reason.
A source your plan does not include still has an entry. On a plan without Cloud Storage Exposure, the Open Cloud Storage entry reads:

Source statuses

A source that fails never fails the search. Treat each entry on its own: partial results are normal. The record re-checks an entry only while it has a task_id and its status is not ok, finished or submission_failed. When a status check fails, the entry keeps its last status. Set your own deadline for each job, and check a job that stops moving on its own endpoint.

Poll the record

Fetch the record by id. Each poll asks every unfinished job for its status, then returns the whole record. Poll every 10 to 30 seconds.
After a few polls, the Open Cloud Storage entry from the example above reads:

Read each source’s findings

Inline sources

data holds the first page of the source’s own search. It also repeats the parameters the platform sent to the source, such as query, q, company or domain. To read more, call the source’s endpoint with those values. Its guide covers paging and filters. A file name search merges several Leaks queries into one page, so that data repeats no query.

Data Brokers

Data Brokers answers inline, with status: "ok" and no task_id. There is no job to follow. Its data carries items, total, limit, next_cursor, sort_by, sort_dir, applied_filters and q, the query the platform sent. total can be null when the count was not computed. When next_cursor is set, pass it as cursor with the same q to read the next page:
Data Brokers covers the listing fields and filters.

Background sources

Read a finished Open Cloud Storage job:
Follow and read the Credentials job. The first search for a domain can take many minutes.
The Credentials entry also carries domain_url and filter_id: 5 for a domain search, and 1 plus filter_parameters with the mailbox name for an email search. Once the job is done, leak_filter_domain_search_results reads the same accounts by domain_url and filter_id, plus filter_parameters for an email search. Filtered credentials covers both reads and the filters.

How your term reaches each source

The platform adapts your term to each source, so a source can match more or less than the same term in an expert search.

List the host names under a domain

Before you run host name searches, find the host names worth searching. retrieve_all_domain_hostnames lists the host names under a domain that appear in leaked records, each with its record count.
  • Pages start at 0. Each page holds 10 host names in alphabetical order. A page that is not a number returns 404.
  • leak_count is a Raw Data count. It is the number of records a Raw Data search for that host name returns. Run host_name_quick_search on a host name to see what those records hold.
  • The list comes from a sample. The host names are read from up to 11,000 Raw Data records that mention the domain, so a widely leaked domain can have host names the list misses. Every listed host name ends with the domain you sent.
  • Results are cached for 24 hours. The first call for a domain runs the searches. Later calls within 24 hours read the same list and counts.
  • Without domain, the call returns an empty hostnames list and total_pages of 1.
The endpoint checks only the license: with no license in force it returns 403 with {"detail": "Your license is not active."}. It has no metered allowance. Each page is one API call.

Errors

A source’s own failure never becomes an HTTP error. It shows as that source’s status in result.
Need one source on its own terms? Search individual data sources queries one indexed source with its own filters. For real-time searches outside the index, use Live search.

Endpoints