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 onesearch_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 infeature_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:
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. Asubmission_failedentry usually addsservice_status_code. When the leak or account index rejects the query, for example for a wildcard it does not support,error_messagecarries its reason.
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 byid. Each poll asks every unfinished job for its status, then returns the whole record. Poll every 10 to 30 seconds.
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, withstatus: "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:
Background sources
Read a finished Open Cloud Storage job:
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. Apagethat is not a number returns404. leak_countis a Raw Data count. It is the number of records a Raw Data search for that host name returns. Runhost_name_quick_searchon 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 emptyhostnameslist andtotal_pagesof1.
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.