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.queryrequired- The question to search for. For a batch, send
user_inputas a list of{"query": "…"}objects. search.providers.include- Only the providers in the list. The pinnable-only providers run only when you name them here.
search.providers.exclude- The default providers, minus the ones in the list.
search.num_results- Results for each provider, not for the request: five providers at
10give fifty results. search.tier- Which fields each result has:
minimalist,default,extendedormax. See the fields per tier. search.auto_routingaccuracy: Telem chooses the providers that answer each query best. See Auto-routing.search.include_domains- Only results from these websites, such as
linkedin.com. Write the host name only. A subdomain is included. search.published_after- 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_before- 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_content- Asks the providers for the whole page rather than a snippet. Slower and more expensive. It works only at the
extendedandmaxtiers. See Full page content.
More fields: search.fields, search.provider_overrides, search.include_raw, session_id, metadata
search.fields- The result fields you want, by name. The tier presets then do not apply.
search.provider_overrides- Options for one provider, keyed by its name. See Provider overrides.
search.include_rawtrueadds each provider's own response, inraw_payload.session_id- Add the call to this session. Without it, Telem starts a new one.
metadata- Query lineage keys. Telem's plugins and integrations send them for you.
Response
200
status- The state of the call, such as
succeeded. preprocessor_runs[]- One run for each provider and query. A provider that fails does not fail the call: its run has an
error. preprocessor_runs[].preprocessor_name- The provider of the run.
preprocessor_runs[].query- The query of the run.
batch_indexis its place in a batch. preprocessor_runs[].output_payload.results[]- The results of the run. They have the same fields whichever provider found them: see the fields per tier.
preprocessor_runs[].error- Why the run failed, or
null. session_id- The session that recorded the call. Send it back as
session_idto add the next call to it. interaction_id- The ID of this call.
normalized_schema_version- The version of the result format:
2. routing- With
auto_routing, one entry for each query: the providers that Telem chose. Without it,null. pinned_providers- The providers you named in
search.providers.include, minusexclude, ornullwhen 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
| Status | Code | When |
|---|---|---|
400 | The 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. | |
401 | The API key is missing or not valid. | |
402 | The account cannot pay for the call. The message says why. | |
403 | The API key is valid but may not make this call. | |
409 | missing_snapshots | The request names earlier context that Telem does not have. Nothing ran. Send it again with that context. |
422 | A field has a value the API does not accept. detail names the field. | |
429 | Your key went over its requests-per-minute cap. Wait for the seconds in Retry-After, then try again. | |
503 | all_providers_failed | Every 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. |
504 | deadline_exceeded | No provider call could start in time. It costs nothing. Try again after a short wait. |
What each error means and what to do: Errors.