Skip to content

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.

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.

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.


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.


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 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.

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.

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"] with providersExclude: ["exa"] searches brave and 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.

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.

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.

Was this page helpful?