Time Search

Run independent relevance searches across time buckets and download the encrypted result set.

POST/search/v2/time-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 from the API Dashboard.

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?

startdate-timerequiredbody

Inclusive timezone-aware start of the range.

Example: 2023-01-01T00:00:00Z

enddate-timerequiredbody

Exclusive timezone-aware end of the range.

Example: 2024-01-01T00:00:00Z

frequencystringbody

Positive interval such as 3h, 1d, 1w, or 1mo. A maximum of 500 buckets may be requested.

Example: 1d

sortenumbody

Chronological ordering of interval searches: ascending or descending.

Example: ascending

require_timezonebooleanbody

Only return documents whose indexed publication timestamp includes a source timezone.

Example: false

n_resultsintegerbody

Maximum results returned per interval search; bucket count multiplied by this value may not exceed 50,000.

Example: 25

n_probesintegerbody

Number of shards evaluated per interval, from 5 to 300.

Example: 30

n_contextifyintegerbody

Context words returned per result, from 128 to 1024.

Example: 128

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 Time Search to run the same relevance search independently across consecutive publication-time intervals. Start is inclusive, end is exclusive, frequency controls bucket width, and the request is limited to 500 buckets and 50,000 requested results. Poll download_from until the encrypted Zstandard payload is ready, then decrypt it with the returned Fernet key.

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 asynchronous time-search task was accepted.

Example: Time search task accepted.

decrypt_usingstring

Fernet key used to decrypt the completed download.

Example: FERNET_KEY

download_fromurl

URL to poll until the encrypted result artifact is ready.

Example: https://storage.example.com/time-search/...

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.