Skip to main content
Live search queries an external source at the moment you ask. You submit a term, DarknetSearch reaches out to the source, and the results reflect what the source shows at that time, including data that is not in the index yet. Two of the three live searches reuse a recent answer for the same term instead of asking the source again; see Live versus indexed. That is the trade-off with quick search and expert search. Those read an index collected ahead of time, so they answer in seconds but only return what has been indexed. A live search takes seconds to minutes and depends on the source being reachable, but it can surface a listing or a page as soon as the source shows it. There are three live searches: Live Data Broker Search has its own queue, capacity limits, filters and acquisition flow, so it has a dedicated guide. This page covers what the three share, then Tor & I2P Network and Email References.

​
Availability and cost

Each live search needs its own plan feature, listed in the table above. Without it, or when your organization’s license is not active, the call that starts the search returns 403:
For Tor & I2P Network and Email References, only the start call checks the plan feature. Their status and results calls need a license in force, and return 403 with {"detail": "Your license is not active."} when it is not. Live Data Broker Search checks the feature on every search call; see its guide. Only Live Data Broker Search has a metered allowance. Tor & I2P Network and Email References are not metered: start as many searches as your rate limit and API Calls allowance permit. Every successful call, polls included, counts as one call toward your API Calls allowance. Poll at the cadence below rather than in a tight loop.

​
The async pattern

Every live search is asynchronous. The first call never returns results.
1

Start the search

POST your term. The response comes back at once with an id and a starting status.
2

Poll until it ends

GET the status with that id until status reaches a final value.
3

Read the results

GET the results with the same id, a page at a time.
The three searches differ in their status values, cadence and paging: Always stop on the failure value as well as the success value, or a failed search keeps your loop running. A Tor & I2P search that runs for 10 minutes, polled every 60 seconds, uses about 10 API calls. Polled every 2 seconds, it uses about 300.

​
Tor & I2P Network

Tor & I2P Network sends your term to a set of darknet search engines over the Tor and I2P networks. It collects every engine’s results, removes duplicates, and has AI score each result for relevance and sensitivity. Every query fans out over slow anonymity networks, so a search takes minutes. Availability: Onion Search. Cost: no metered allowance.
1

Start the search

external_sources_search takes a JSON body:
To run several terms in one search, put one term per line in query. Lines shorter than 3 characters are skipped, and at most 100 distinct terms run. Every term goes to every engine.
2

Poll until it ends

Call external_sources_search_status with the id. The path has no trailing slash.
status moves from queued to running, then ends at completed or error. resultCount is set once every engine has answered. The AI scoring runs after that, while status is still running, so read the results after completed. states is always empty.
3

Read the results

Call external_sources_search_results with the same id.
  • page starts at 0. size is 10 to 100, default 10.
  • ordering takes ai_relevance_score, created_at or date, where date is the date the engine reported for the page. Prefix - for descending. The default is the highest relevance first, then the newest date. In descending relevance order, results without a relevance score come before scored ones.
The results page holds content, the rows, and the paging fields number, size, totalElements, totalPages, numberOfElements, first, last and hasContent. Stop when last is true.
For a result that was not scored, aiRelevanceScore, aiSensitivity and aiReasoning are null and aiKeywords is empty. An unknown id, or the id of another organization’s search, returns 404. A page past the last page returns 404 with {"detail": "Invalid page."}.

​
Email References

Email References finds the email addresses published for an organization on the web. Each result names the person, their position, department and seniority, and when the address was last seen. The more pages an address appears on, the larger that person’s exposure. Results for the same domain and company_name searched in the last 14 days are reused rather than fetched again. Such a search finishes quickly and returns the stored set. Availability: Email Exposure (Surface Web). Cost: no metered allowance.
1

Start the search

mails_external_search takes domain, company_name or both. Each is up to 255 characters, and at least one is required.
A body with neither field returns 400 with {"non_field_errors": ["Either domain or company_name must be provided."]}.
2

Poll until it ends

Call mails_external_search_status with the id. status moves from Pending to Running, then ends at Finished or Error.
3

Read the results

Call mails_external_search_results with the same id.
  • page starts at 1. size defaults to 10, max 100.
  • The response holds count, results, and next and previous. Page by raising page until next is null. The next and previous URLs point at an internal service, so don’t call them.
Narrow and sort the results with query parameters on the results call. The filters apply to results, not to the start call. Each result row holds: An unknown id, or the id of another organization’s search, returns 404.

​
Live versus indexed

Reach for live search when freshness matters or the source is not in the index. Reach for quick or expert search when you need a fast answer from data already collected. Searching DarknetSearch compares all three approaches.

​
Endpoints

The Live Data Broker Search endpoints are listed in its guide.