Skip to content

Search and fetch

Search

Run a search. Send one query, or a batch of them. Telem sends each query to the providers at the same time and returns one result list per provider.

POST/v1/search

Send your API key as Authorization: Bearer. See Authentication. How each option works: Search parameters.

Request body

user_input.querystringrequired
The question to search for. For a batch, send user_input as a list of {"query": "…"} objects.
search.providers.includestring[]
Only the providers in the list. The pinnable-only providers run only when you name them here.
search.providers.excludestring[]
The default providers, minus the ones in the list.
search.num_resultsintegerdefault 51 to 20
Results for each provider, not for the request: five providers at 10 give fifty results.
search.tierstringdefault "default"one of minimalist, default, extended, max
Which fields each result has: minimalist, default, extended or max. See the fields per tier.
search.auto_routing"accuracy"
accuracy: Telem chooses the providers that answer each query best. See Auto-routing.
search.include_domainsstring[]1 to 20 items
Only results from these websites, such as linkedin.com. Write the host name only. A subdomain is included.
search.published_afterstring (date-time)
Keeps the results published on or after this date or time, such as 2026-09-01. A result with no known date is kept.
search.published_beforestring (date-time)
Keeps the results published before this date or time. A date with no time includes that day. A result with no known date is kept.
search.include_full_contentbooleandefault false
Asks the providers for the whole page rather than a snippet. Slower and more expensive. It works only at the extended and max tiers. See Full page content.
More fields: search.fields, search.provider_overrides, search.include_raw, session_id, metadata
search.fieldsstring[]
The result fields you want, by name. The tier presets then do not apply.
search.provider_overridesobject
Options for one provider, keyed by its name. See Provider overrides.
search.include_rawbooleandefault false
true adds each provider's own response, in raw_payload.
session_idstring (UUID)
Add the call to this session. Without it, Telem starts a new one.
metadataobject
Query lineage keys. Telem's plugins and integrations send them for you.

Response

200

statusstring
The state of the call, such as succeeded.
preprocessor_runs[]object[]
One run for each provider and query. A provider that fails does not fail the call: its run has an error.
preprocessor_runs[].preprocessor_namestring
The provider of the run.
preprocessor_runs[].querystring
The query of the run. batch_index is its place in a batch.
preprocessor_runs[].output_payload.results[]array
The results of the run. They have the same fields whichever provider found them: see the fields per tier.
preprocessor_runs[].errorobject or null
Why the run failed, or null.
session_idstring (UUID)
The session that recorded the call. Send it back as session_id to add the next call to it.
interaction_idstring (UUID)
The ID of this call.
normalized_schema_versioninteger or null
The version of the result format: 2.
routingobject[] or null
With auto_routing, one entry for each query: the providers that Telem chose. Without it, null.
pinned_providersstring[] or null
The providers you named in search.providers.include, minus exclude, or null when you named none. These are the providers you asked for, not the ones that ran.

created_at, completed_at: when Telem received the call and when it finished.

The response also has instance_id, trajectory_id, parent_trajectory_id, trajectory_goal, postprocessor_runs, missing_snapshots, client_advisory. You do not need them to read the results.

Errors

StatusCodeWhen
400The request is not correct, such as an unknown provider, a provider in both include and exclude, or an override for a provider that you did not name.
401The API key is missing or not valid.
402The account cannot pay for the call. The message says why.
403The API key is valid but may not make this call.
409missing_snapshotsThe request names earlier context that Telem does not have. Nothing ran. Send it again with that context.
422A field has a value the API does not accept. detail names the field.
429Your key went over its requests-per-minute cap. Wait for the seconds in Retry-After, then try again.
503all_providers_failedEvery provider call failed, so there are no results. detail.reason gives the cause. A 503 whose detail is plain text was refused before the search ran and costs nothing.
504deadline_exceededNo provider call could start in time. It costs nothing. Try again after a short wait.

What each error means and what to do: Errors.

Was this page helpful?