Bulk Search

Request up to 10,000 ranked results for asynchronous processing.

POST/search/v2/bulk-search

Related NOSIBLE resources

research & data

Inspect the Search data dictionary or read NOSIBLE research for implementation context and methods.

Authorizations

apiKey

Api-Keystringrequiredheader

Your NOSIBLE API key.

Example: nos_sk_...

Body

application/json

questionstringbody

The question the search should answer. 1–500 characters; use this as the primary information need.

Example: What is driving AI chip demand?

n_resultsintegerbody

Number of results to prepare. Bulk Search accepts 1,000–10,000 and returns an encrypted download rather than inline results.

Example: 1000

instructionstringbody

Instruction passed to the embedding mode. Keep it short and purposeful; it is not a replacement for the question.

Example: Retrieve evidence about semiconductor demand.

expansionsstring[]body

Up to 10 semantically or lexically related formulations that broaden recall without changing the underlying intent.

Example: ["AI accelerator demand", "data-center GPU spending"]

sql_filterstringbody

Optional SQL expression over indexed document metadata. Common columns include netloc, published, modified, visited, words, and chars.

Example: SELECT loc FROM engine WHERE words >= 30

algorithmenumbody

Scoring algorithm. hybrid-3 is the recommended default for general-purpose retrieval.

Example: hybrid-3

min_similaritynumberbody

Reject results below this similarity threshold. Must be between 0 and 1; it is a score threshold, not a probability.

Example: 0.35

must_includestring[]body

Terms that must appear in each result. Use sparingly: every additional hard constraint can reduce recall.

Example: ["NVIDIA"]

must_excludestring[]body

Terms that must not appear in a result.

Example: ["job listing"]

brand_safetyenumbody

Content-safety class: Safe, Sensitive, or Unsafe.

Example: Safe

languageenumbody

Language classification used to refine retrieval, such as EN, FR, or DE.

Example: EN

continentenumbody

Continent filter for the indexed document.

Example: Europe

regionenumbody

Geographic region filter for the indexed document.

Example: Western Europe

countryenumbody

Country filter using the API's canonical country values.

Example: Germany

sectorenumbody

GICS sector filter.

Example: Information Technology

industry_groupenumbody

GICS industry-group filter.

Example: Semiconductors & Semiconductor Equipment

industryenumbody

GICS industry filter.

Example: Semiconductors

sub_industryenumbody

GICS sub-industry filter.

Example: Semiconductor Equipment

iab_tier_1enumbody

IAB tier-1 content category.

Example: Business

iab_tier_2enumbody

IAB tier-2 content category.

Example: Business Services

iab_tier_3enumbody

IAB tier-3 content category.

Example: Investing

iab_tier_4enumbody

IAB tier-4 content category.

Example: Stocks

companiesstring[]body

Up to three company names used to refine retrieval.

Example: ["NVIDIA", "TSMC"]

collectionenumbody

Collection to search. everything searches the full available collection; this-week restricts to recently added data.

Example: everything

deduplicatebooleanbody

Deduplicate results that represent the same headline or story.

Example: true

How to use this endpoint

guidance

Use Bulk Search when you need the long tail rather than the first page of ranked results. The request is accepted immediately; wait for the result object to become available, then download and decrypt the compressed payload. Treat decrypt_using as secret key material, keep the presigned URL private, and follow the cURL/Python example's Fernet then Zstandard order rather than attempting to parse the download as JSON.

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

messagestring

Acknowledgement that the long-running task was accepted.

Example: Slow search task accepted.

download_fromstring

Short-lived object-store URL for the encrypted result file. Download it only from a trusted worker and do not log or share it.

Example: https://s3.eu-west-1.wasabisys.com/...

decrypt_usingstring

Fernet key material required to decrypt the downloaded bytes before Zstandard decompression. Treat it as a secret and destroy it after use.

Example: base64-encoded-key

Responses and errors

HTTP

200Request succeeded. The response body is shown in the panel on the right.

400invalid_request — The request is syntactically valid JSON but a value, date, filter, or combination of fields is invalid.

401unauthorized — The required API key or Bearer credential is missing or invalid.

422validation_error — The request shape is understood but one or more values fail validation.

429rate_limited — The request exceeded the account or public-window rate limit. Respect Retry-After when supplied.

502upstream_error — An upstream retrieval service failed while processing the request.

504upstream_timeout — An upstream retrieval service did not respond within the request timeout.

409bulk_search_in_progress — Another bulk job is already running for this account; wait for its download before submitting another.