Parameters
Parameters
The Telem search and fetch parameters, such as providers, tiers, results per provider and full-page content, and how the plugins save them.
This page lists the request parameters that are useful to set, with what each one does and costs. The last section shows how the plugins and the SDK save them. Each option has one line below. What each option does is on Search parameters and Fetch parameters. The API reference is generated from the server’s own schema.
Connecting
Section titled “Connecting”TELEM_API_KEY is your credential. TELEM_BASE_URL points a client at a
deployment other than the hosted one. It defaults to https://router.telem.ai.
Both are environment variables. The guided installer writes your key to
~/.telem/credentials.json, so usually you do not set either one by hand. For
the full rules, see API keys.
For a private deployment, give the installer both of its urls: --base-url for the
REST endpoint and --mcp-url for the MCP endpoint, path included. It saves them in
~/.telem/credentials.json as baseUrl and mcpUrl, so later runs keep them.
mcpUrl is written only when it is not the hosted endpoint.
Search
Section titled “Search”You set all search options in the request’s search block:
{ "user_input": { "query": "istio vs linkerd" }, "search": { "tier": "extended", "providers": { "include": ["exa", "brave"] }, "num_results": 5 }}| Parameter | What it does |
|---|---|
auto_routing |
Let Telem pick the providers that answer each query best. See Auto-routing. |
tier |
How much detail each result has. See Tier. |
fields |
Name the result fields you want instead of a tier. Mutually exclusive with tier. |
providers.include |
Replace the deployment’s provider set. See Providers. |
providers.exclude |
Drop providers from the set that would otherwise run. |
num_results |
Results per provider, 1 to 20. See Results per provider. |
include_full_content |
Ask providers for whole page content. See Full page content. |
provider_overrides |
Pass provider-native parameters through, keyed by provider. See Provider overrides. |
include_raw |
Return each provider’s original payload alongside the normalized results. See Raw provider payloads. |
published_after, published_before |
Get only results published in a date window. See Publication date. |
include_domains |
Get only results from a list of domains. See Domains. |
Search parameters →: what each option does, what it costs, and the raw field behind each normalized field, for each provider.
POST /v1/fetch reads whole web pages by URL. One call can read several pages,
fetched as one batch. You set all fetch options in the request’s options
block:
{ "urls": ["https://example.com/a", "https://example.com/b"], "options": { "tier": "extended", "content_format": "markdown" }}| Option | Type | Default | What it does |
|---|---|---|---|
tier |
minimalist | default | extended | max |
"default" |
How much each page includes. See Tier. |
content_format |
"markdown" | "text" |
"markdown" |
Format of the page body. See Page content. |
inline_content |
bool |
true |
false returns the metadata without the page text. See Page content. |
inline_max_chars |
int |
20 000 | Per-page cap. Longer pages are truncated and flagged. See Page content. |
providers |
array<string> |
the deployment’s chain, in order | Pin the chain to specific providers. See Providers. |
Fetch parameters →: the tiers, the provider chain, and the raw field behind each normalized field, for each provider.
Request limits
Section titled “Request limits”Each request has size limits, such as 32 queries in a batch. They are on Rate limits.
Some events are not fatal. For example, a provider clamped your count, or a
provider by design cannot supply a field that you asked for. These events come
back as {code, message} entries in each run’s warnings. They never come back
as errors.
Configuring the plugins and the SDK
Section titled “Configuring the plugins and the SDK”The plugins and the SDK send the same request. A config file or an environment variable sets a parameter’s value. Then every search that they make includes that value.
This section covers the surfaces that run on your machine:
- the Python and JavaScript SDKs
- the OpenCode, Pi, DeepSeek Harness and Hermes plugins
The Agent skill reads no config file: the agent puts the options in each request.
The Claude Code plugin, the
Codex install, the Grok Build install,
the Muse Code install, the
VS Code install, the
Cursor install and the
Devin Desktop install reach Telem through the hosted
MCP server (mcp.telem.ai), or through a private deployment’s MCP endpoint when you
install with --mcp-url. The hosted server runs on Telem’s infrastructure and reads
none of your files. The options below still apply to these seven. Each plugin or hook
resolves your config and sends it with every search and page read it makes.
The copy-paste setup for other MCP clients has no plugin with it, so it reads
no file. It takes its settings from connection headers instead:
X-Telem-Tier, X-Telem-Providers-Include, X-Telem-Providers-Exclude and
X-Telem-Auto-Routing for search, and X-Telem-Fetch-Providers,
X-Telem-Fetch-Tier and X-Telem-Fetch-No-Cache for page reads. See
MCP server.
Options go in .telem/telem.json. You can have one file for each project and
one for each user:
{ "tier": "extended", "providersInclude": ["exa", "brave"]}| Request parameter | File key | Environment |
|---|---|---|
search.tier |
tier |
TELEM_TIER |
search.fields |
fields |
TELEM_FIELDS (comma-separated) |
search.providers.include |
providersInclude |
TELEM_PROVIDERS_INCLUDE (comma-separated) |
search.providers.exclude |
providersExclude |
TELEM_PROVIDERS_EXCLUDE (comma-separated) |
search.include_full_content |
fullContent |
TELEM_FULL_CONTENT (only the exact string 1) |
search.auto_routing |
autoRouting |
TELEM_AUTO_ROUTING |
Three more keys set the page-fetch options, for telem_fetch:
| Request parameter | File key | Environment |
|---|---|---|
options.providers |
fetchProviders |
TELEM_FETCH_PROVIDERS (comma-separated) |
options.tier |
fetchTier |
TELEM_FETCH_TIER |
options.no_cache |
fetchNoCache |
TELEM_FETCH_NO_CACHE (only the exact string 1) |
| Surface | Sends the fetch keys |
|---|---|
| Claude Code, Codex, VS Code, Cursor, Devin Desktop | From .telem/telem.json. The hook also reads the TELEM_FETCH_* variables, but it is not yet confirmed that these hosts pass your shell’s environment to the hook, so set the keys in the file. |
| Grok Build | From .telem/telem.json and the TELEM_FETCH_* variables: Grok gives your environment to the hook. Only in a folder you trust. |
| Muse Code | From .telem/telem.json only. Muse Code does not give your environment to the hook, so the TELEM_FETCH_* variables do not apply. |
| Pi (extension and skill) | From .telem/telem.json and the TELEM_FETCH_* variables. |
| DeepSeek Harness | From its plugin config, .telem/telem.json and the TELEM_FETCH_* variables. |
| Python SDK | Arguments to fetch() (providers, tier, no_cache), else the TELEM_FETCH_* variables. It reads the file only when you call telem.resolve_fetch_options(). |
| Hermes | From .telem/telem.json and the TELEM_FETCH_* variables. |
| JavaScript SDK | Options to fetch() (providers, tier, noCache), else the TELEM_FETCH_* variables. It reads no file. |
| OpenClaw | From its plugin entry and the TELEM_FETCH_* variables. |
| OpenCode | From its options object, .telem/telem.json and the TELEM_FETCH_* variables. |
| MCP server | From the X-Telem-Fetch-* headers on the connection. See MCP server. |
| Agent skill | No file or variable. Options go in the request body that the agent writes. |
Pinning the fetch provider
Section titled “Pinning the fetch provider”fetchProviders replaces the fetch provider chain with your list, in your order. One
name means no failover: if that provider cannot read a page, the URL fails.
fetchTier sets how much each page includes, and is not case-sensitive. On the hosted
MCP server, a tier above extended is lowered to extended. fetchNoCache: true
reads every page live.
A pin or fetchNoCache changes which provider you pay for, and the pages that it
reads are not saved for later reads. A key in a committed project file applies to
everyone who works in that project.
num_results is only a call argument. It has no file key. Pass it with each
search, for example client.search(..., num_results=10), or
telem.search(..., { numResults: 10 }) in JavaScript.
The JavaScript SDK reads the TELEM_* variables and the credentials file only.
It never opens .telem/telem.json. Set its search defaults as constructor options
(new Telem({ tier: "extended" })) or call arguments. The environment variables
have lower priority.
The Python SDK does not open .telem/telem.json either. Set its search
defaults as constructor arguments (Telem(default_tier="extended")) or call
arguments. The TELEM_* variables have lower priority. To use the files, call
resolve_search_options() and pass .search_kwargs() to client.search.
Precedence
Section titled “Precedence”The order is: project file, then user file, then TELEM_*. The order applies
per key. A project file that sets only tier leaves the other keys to the
levels below it. The order also applies per call. An edit takes effect on
the next search, with no restart.
OpenClaw is the exception. It has no .telem/telem.json layer. Its options and
its credentials are in its own plugin config, with TELEM_* below it. For the
API key, it then falls back to ~/.telem/credentials.json.
Two plugins add one level above the files. OpenCode reads its plugin options
object first. The DeepSeek Harness plugin reads its row in your profile patch
first. Then each reads the project file, the user file and TELEM_*. On DeepSeek
Harness, the project is the calling agent’s session directory.
OpenCode and Pi still read two older files each, above the user file:
.opencode/telem.json and ~/.config/opencode/telem.json for OpenCode, and
.pi/telem.json and ~/.config/pi/telem.json for Pi. Both warn that the files are
deprecated. Pi reads its project files only in a trusted project.
The installer sets autoRouting for you, and asks nothing about it. It writes
accuracy, or keeps the value that ~/.telem/telem.json already has. To choose when
you install, pass --auto-routing accuracy or --auto-routing off.
accuracy is the only mode, and off turns it off. Any other value makes every
search fail with a 422.
autoRouting is the one exception to that order. TELEM_AUTO_ROUTING has
priority over both files. So an operator can change the mode for one shell and
not edit a file. A mode (accuracy today) lets the server choose which providers
run each search, and what to optimise for. With off, or with no key, the
configured provider set runs unchanged. To learn what auto-routing does, see
Auto-routing.
tier and fields are mutually exclusive. When both are set, the more specific
level wins.
When include and exclude name the same provider
Section titled “When include and exclude name the same provider”The exclude list wins, on every surface:
- Some providers are left. They run, with a warning.
providersInclude: ["exa", "brave"]withprovidersExclude: ["exa"]searchesbraveand warns[telem] providersExclude removes exa from providersInclude: this search runs brave. - No provider is left. The search is refused, and nothing is sent. The default
providers never run in its place. The message names the provider, and where each
list came from, so you know which one to edit. For example:
[telem] providersExclude removes every provider in providersInclude (exa), so no provider is left and no search was sent. Remove exa from one of the two lists in the project's .telem/telem.json.
How each surface shows the refusal:
| Surface | What you see |
|---|---|
| OpenCode, Pi, DeepSeek Harness, OpenClaw | A tool error with the message. |
| Claude Code, Codex, Grok Build, Muse Code, VS Code | The hook denies the telem_search call, with the message as the reason. On Muse Code only the model gets the message: muse exec shows you nothing. telem_fetch still runs with your fetch settings, without your search options. This is the only config problem that stops a call; any other costs only your options, and the call still runs. |
| Pi skill | search.mjs exits with code 1 and prints Error: <message>. |
| Hermes | The tool raises the message before any request, the same way as its other input errors. |
| Python SDK | ValueError before anything is sent. The message names providers_include and providers_exclude. |
| JavaScript SDK | TelemError with code invalid_request, before anything is sent. |
| MCP server | The X-Telem-Providers-* headers are checked when the client connects. If they leave no provider, the connection is refused. |
| HTTP API | Lists that only partly overlap run what is left, with a providers_excluded warning. No provider left is a 400. |
An SDK call that sends an empty include list on its own still gets the server’s
400.
Incremental transmission
Section titled “Incremental transmission”These clients send conversation lineage incrementally by default:
- the OpenCode, OpenClaw and Pi plugins
- the Python SDK’s OpenAI and Hermes integrations
- the JavaScript SDK’s Vercel AI SDK integration
A subagent’s inherited context is sent once, not on every search. Before the client leaves anything out, it checks that the backend supports this. Older or self-hosted backends keep getting the full payload.
TELEM_INCREMENTAL=off (environment only, no file key) sends the full payload on
every call again. Use it only to roll back this behavior, not to tune anything.
Lineage data that you build by hand with buildMetadata is sent in full on
every call.
The DeepSeek Harness plugin does not do this yet. Every search it makes sends the full lineage payload, including a subagent’s inherited context. This does not affect correctness. The plugin only sends more bytes, and no data is missing.
Update notice
Section titled “Update notice”These clients show a one-time notice when a newer plugin or SDK version is available:
- the OpenCode, OpenClaw and Pi plugins
- the Python SDK’s OpenAI and Hermes integrations
The notice names the exact command to update. It only notifies you. It never
updates or installs anything on its own. By default, it stays quiet in
non-interactive and CI runs. To silence the “a newer version is available”
notice, set TELEM_NO_UPDATE_NOTICE=1 (environment only, no file key).
The JavaScript SDK shows no notice, and the DeepSeek Harness plugin shows
none either. Update that plugin with
dsh plugin --profile <name> add @telemai/dsh-plugin when you choose to.
Next steps
Section titled “Next steps”- Search parameters: what each search option does and costs
- Fetch parameters: what each fetch option does
- Auto-routing: let Telem choose the providers for each query
- Errors: every error the API returns