Parameters
Search parameters
Every option on a Telem search: auto-routing, tiers and fields, provider lists and overrides, raw payloads, batching, and where each field comes from.
This page tells you what each search option does and costs, and where each
response field comes from. You set all search options in the request’s search
block. The block itself and a one-line summary of each option are on
Parameters.
Auto-routing
Section titled “Auto-routing”auto_routing · "accuracy" · off by default.
Set auto_routing, and Telem picks the providers for you: a smart routing
technique sends each query to the providers that answer it best. Each query in a
batch gets its own choice.
{ "user_input": { "query": "papers on speculative decoding for LLM inference" }, "search": { "auto_routing": "accuracy" }}The routing block in the response shows what Telem
chose.
accuracy is the only mode at this time.
In the SDKs, the same option is client.search(..., auto_routing="accuracy") in
Python and telem.search(..., { autoRouting: "accuracy" }) in JavaScript. The
plugins read it from your config file, and the installer can set it for you. See
Configuring the plugins and the SDK.
Which providers Telem can choose
Section titled “Which providers Telem can choose”| Your request | Telem chooses from |
|---|---|
No providers block |
All providers that the deployment runs, except serpapi and the pinnable-only providers |
providers.include |
Only the providers in the list. Name serpapi or a pinnable-only provider here to let Telem choose it. |
providers.exclude |
All providers that the deployment runs, minus the list, serpapi and the pinnable-only providers |
serpapi is slow, so Telem does not choose it unless you include it. The
pinnable-only providers, such as the site providers,
run only when you name them.
The routing block
Section titled “The routing block”With auto_routing, the response has a routing list. It has one entry for
each query, in the order of the batch:
"routing": [ { "providers": ["…", "…", "…"] }]| Field | What it is |
|---|---|
providers |
The providers that Telem chose, best first. |
Without auto_routing, routing is null.
If routing is not available, every query runs on the default providers. Each
run’s warnings then has a routing_unavailable entry.
One of minimalist, default, extended, max. Default "default".
The tier decides how much each result includes and which options the adapters send upstream. So the tier affects the price as well as the detail. The sets are cumulative. To choose one, see Search best practices.
| Tier | Adds |
|---|---|
minimalist |
url, title, rank, latency_ms, warnings |
default |
summary |
extended |
excerpt, full_content †, publish_date, usage |
max |
thumbnail, favicon, source, enrichments, fetch_meta, answer, entities, related, verticals |
† full_content never arrives on the tier alone. See
Full page content.
A field in the active set is present on every result. It is null or [] when
the provider cannot supply it. Fields outside the set are absent.
latency_ms and warnings are always present.
fields is the explicit alternative. List any of the names above, and the tier
presets do not apply.
Where each field comes from
Section titled “Where each field comes from”One vocabulary, whoever answered. summary is always the result’s text
snippet. The provider can call it description (brave), content (tavily) or
highlights (exa). Telem maps every provider’s response into these fields on
the server. It never invents a value. A field that the provider cannot supply
comes back null ([] for list fields), with a capability_gap warning. To
get the original payload as the provider sent it, set
include_raw.
The tabs below name the raw field behind each normalized field. Three fields are the same for every provider, so the tabs leave them out:
rankis the row’s position in the provider’s own order.source.domaincomes from the result’s URL.enrichmentskeeps, verbatim, every provider-specific key that normalization did not use.
| Normalized | Read from |
|---|---|
url / title |
url / title |
summary |
summary, else highlights (below max) |
excerpt |
highlights (10k shape; paid, max/fields mode) |
full_content |
text (paid; max/fields mode) |
publish_date |
publishedDate |
usage |
costDollars |
thumbnail / favicon |
image / favicon |
answer |
output (deep runs via overrides) |
source.author |
author |
Cannot supply: entities, related, verticals, fetch_meta. These come back null with a capability_gap warning. If you request enrichments on exa, Telem requests exa’s paid extras option.
| Normalized | Read from |
|---|---|
url / title |
url / title |
summary |
content (first chunk when advanced depth is engaged) |
excerpt |
content, chunked (paid advanced depth) |
full_content |
raw_content |
favicon |
favicon |
usage / answer |
usage / answer |
related |
follow_up_questions |
verticals |
images |
Cannot supply: publish_date, thumbnail, entities, fetch_meta.
| Normalized | Read from |
|---|---|
url / title |
url / title (in web.results[]) |
summary |
description |
excerpt |
extra_snippets |
publish_date |
page_age |
thumbnail / favicon |
thumbnail.src / meta_url.favicon |
source.name |
profile.name |
entities |
infobox |
related |
faq questions + discussions titles |
verticals |
news, videos, locations |
fetch_meta |
fetched_content_timestamp |
Cannot supply: full_content, usage, answer.
| Normalized | Read from |
|---|---|
url / title |
url / title (in results[]) |
summary |
snippet |
full_content |
snippet (the same field, as markdown, requested at its longest) |
publish_date |
date |
Cannot supply: excerpt, thumbnail, favicon, usage, answer, entities, related, verticals, fetch_meta. One text field feeds both summary and full_content. So Telem asks for more of it as you ask for more. Below extended, you get a short snippet. At extended and max, you get a longer one. When you opt into full content, you get the longest. All three lengths cost the same. last_updated goes in enrichments.
| Normalized | Read from |
|---|---|
url / title |
url / title |
summary |
excerpts[0] |
excerpt |
excerpts |
publish_date |
publish_date |
usage |
usage (SKU list) |
Cannot supply: full_content, thumbnail, favicon, answer, entities, related, verticals, fetch_meta.
| Normalized | Read from |
|---|---|
url / title |
url / title (in results.web[]) |
summary |
description |
excerpt |
snippets |
full_content |
contents.markdown (paid livecrawl; max/fields mode) |
publish_date |
page_age |
thumbnail / favicon |
thumbnail_url / favicon_url |
verticals |
results.news |
Cannot supply: usage, answer, entities, related, fetch_meta.
| Normalized | Read from |
|---|---|
url |
url |
title |
name |
summary |
content |
full_content |
content (free at extended; at max, Telem uses the paid deep depth) |
favicon |
favicon |
Cannot supply: excerpt, publish_date, usage, thumbnail, answer, entities, related, verticals, fetch_meta.
| Normalized | Read from |
|---|---|
url / title |
url / title (in result.results[]) |
summary |
description |
full_content |
description (same field, as text) |
Cannot supply: everything else.
| Normalized | Read from |
|---|---|
url |
url (in documents[]) |
summary |
content |
full_content |
content |
publish_date |
published_date |
Cannot supply: title (none by API design, so always null) and everything else.
| Normalized | Read from |
|---|---|
url / title |
link / title (in organic_results[]) |
summary |
snippet |
publish_date |
date (some rows only) |
thumbnail / favicon |
thumbnail / favicon |
source.name |
source |
answer |
answer_box.answer, else .snippet |
entities |
knowledge_graph |
related |
related_questions + related_searches |
verticals |
top_stories, answer_box, ai_overview, inline_* |
Cannot supply: excerpt, full_content, usage, fetch_meta.
| Normalized | Read from |
|---|---|
url / title |
url / title (in results[]) |
summary |
snippet |
publish_date |
date (news and some web rows) |
thumbnail |
thumbnail_url |
source.name |
site_name |
Cannot supply: excerpt, full_content, favicon, usage, answer, entities, related, verticals, fetch_meta. Vertical-specific keys go in enrichments. Examples are a news row’s publisher, and a research paper’s authors, venue and citations.
Providers
Section titled “Providers”providers.include replaces the deployment’s default provider set. It does
not add to it. providers.exclude removes providers from the set that would
otherwise run. More providers give better recall and a bigger bill. With an
explicit list, you decide what a search costs. Social, video, review and
shopping platforms have their own pinnable-only search providers. They are
listed on Supported platforms.
The response names your pin in pinned_providers: the include list without
duplicates, minus exclude. It is null when you did not name providers. An
exclude list alone, a tier or provider overrides are not a pin. It lists the
providers you named, not the ones that ran, so a provider that a date or domain
filter dropped is still in it. With auto-routing, your include list is the set
Telem chooses from, and routing shows what it chose.
| Provider | Notes |
|---|---|
brave |
|
ceramic |
No count option upstream. num_results is enforced by trimming the results. |
exa |
Embedding-based; matches on meaning. num_results is clamped to 10. |
linkup |
|
parallel |
|
perplexity |
One text field per result feeds both summary and full_content. num_results is sent as it is, with no clamp and no trim. |
seltz |
No title by API design. title is always null. |
serpapi |
No count option upstream. num_results is enforced by trimming the results. |
tavily |
|
tinyfish |
No count option upstream. Every call returns one page of 10, trimmed to num_results. If you ask for more than 10, you get a capability_gap warning. |
you |
An unknown name returns a 400 that lists the known names. A provider named
in both providers.include and providers.exclude is taken out of include:
the other providers run, and the response gets a providers_excluded warning.
If no provider is left, the request returns a 400. An excluded provider is
also kept out of auto-routing. See
When include and exclude name the same provider.
You can name any provider above, whether or not the deployment runs it by default.
GET /v1/preprocessors (no auth) is the live list of providers. For each
provider, it gives the slug, whether it runs by default (active_by_default), and
whether auto-routing can choose it when you send no provider list (auto_routed).
It can also list entries that you cannot use in a search.
Provider overrides
Section titled “Provider overrides”Normalization covers the portable options. For each provider’s native options,
use provider_overrides. It is keyed by provider. Telem deep-merges it into the
request that it builds for that provider. So you can set an option that only
one provider has in one line:
{ "search": { "providers": { "include": ["exa", "tavily"] }, "provider_overrides": { "exa": { "category": "news" }, "tavily": { "search_depth": "advanced" } } }}Overrides are explicit intent, so Telem blocks almost nothing. These limits remain:
- You can only override providers that the request names. Otherwise you get a 400.
- The whole block caps at 16 KB.
- Count options (
num_results,max_results,countand similar, at any depth) cap at 20. They still count toward the volume budget.
Native options are not portable, on purpose. Keep each one under its provider’s key. Expect paid features, such as tavily’s advanced depth, to add to the bill.
The providers on Supported platforms are the exception. Each accepts only a few overrides, often none. Any other override returns a 400.
Raw provider payloads
Section titled “Raw provider payloads”include_raw: true returns each provider run’s original response, as the
provider sent it. It is under that run’s raw_payload, next to the normalized
results. Use it when you need something that the normalized response does not
include, such as a provider’s own relevance score. It is off by default. The
payloads are big.
Results per provider
Section titled “Results per provider”num_results · 1 to 20 · default 5. The count is per provider, not per
request. Five providers at num_results: 10 give fifty rows.
Publication date
Section titled “Publication date”published_after · published_before · not set by default.
Use these two parameters to get only results that were published in a date window. Each value is a date or a date and time in ISO 8601 format. A value with no time zone is in UTC.
| Parameter | Results that Telem keeps |
|---|---|
published_after |
Results published on or after this date or time. |
published_before |
Results published before this date or time. A date with no time includes all of that day. |
You can set one parameter or both. If the window is empty, the request fails with a 422.
{ "user_input": { "query": "EU AI Act enforcement news" }, "search": { "published_after": "2026-09-01", "published_before": "2026-09-30" }}This search keeps results published from 1 September 2026 to the end of 30 September 2026, in UTC.
Telem keeps a result that has no known publication date. Some providers do not
give a date for every result. When either parameter is set, every result
has publish_date. It is empty when the date is unknown.
These two parameters apply to one search only. You cannot set them in a config
file or in an environment variable. In the SDKs, the names are
published_after (Python) and publishedAfter (JavaScript), and the same for
published_before. An agent that uses the telem_search tool can set them on
each call.
Domains
Section titled “Domains”include_domains · not set by default.
Use this parameter to get only results from some websites. The value is a list
of 1 to 20 domain names, such as linkedin.com. Write the host name only: no
https:// and no path. A subdomain is included: linkedin.com also gives
results from uk.linkedin.com.
{ "user_input": { "query": "data engineer jobs in Berlin" }, "search": { "include_domains": ["linkedin.com", "indeed.com"] }}This search keeps only results from linkedin.com, indeed.com and their
subdomains. Telem keeps your query text: a site: that you write in the query
is sent as you wrote it. Some providers get your domains added to the query as
site: terms.
A provider that cannot search by domain is not used for the request, unless you
name it in providers.include. If a name is not a domain name, or the list has
more than 20 names, the request fails with a 422.
This parameter applies to one search only. In the SDKs, the name is
include_domains (Python) and includeDomains (JavaScript).
Full page content
Section titled “Full page content”include_full_content: true asks providers for the whole page body in place of
a snippet. It is slower and more expensive, and it is off unless you set it.
The flag keeps the full_content field that a tier already has. It never adds
the field. At extended and max, the field fills. At minimalist and
default, the flag does nothing, because those tiers have no full_content
field to keep. Naming full_content in fields opts in the same way. Opting in
also allows the paid content option wherever a provider has one:
exaandyousupply page text only attier: "max"(or infieldsmode).linkupreturns it fromextendedup, and uses its deeper paid mode atmax.perplexityreturns it fromextendedup at no extra cost. It is the longest form of the same text that fillssummary.
Whole pages are rarely the best input for a model, and every one costs money.
It is cheaper to search at default, then fetch
only the URLs that you keep.
Batch query
Section titled “Batch query”Pass a list of queries, and they run concurrently in a single interaction. Each result is tagged with the query that produced it. This is faster and cheaper than calling search many times.
{ "user_input": [ { "query": "istio vs linkerd" }, { "query": "envoy gateway api" } ] }In the Python SDK, this is client.search(["q1", "q2"]).
Next steps
Section titled “Next steps”- Auto-routing: what auto-routing does and how to turn it off
- Fetch parameters: read whole pages for the URLs that you keep
- Supported platforms: search providers for social, video, review and shopping platforms
- Errors: every error the API returns