Quickstart
Get an API key and make your first search call in a few minutes.
Telem
Route agent web searches and inspect the traces.
Route searches across providers, fetch pages clean, observe every step.
Install
Section titled “Install”curl -fsSL https://docs.telem.ai/install.sh | shIt asks before changing anything and sets up the agents you pick. Keys come from
the console; searches show up there too. --dry-run
previews. Prefer a skill, MCP, Python, JavaScript, or plain REST? The
quickstart walks every path.
Then your agent just has it. A real opencode run, replayed — the model
reaches for telem_search on its own, sends both angles as one interaction,
then reads the winning pages with telem_fetch.
Every one of those calls lands in the console as a session trajectory. Same two tools on Claude Code, Codex, OpenClaw and Pi — OpenCode setup →
One call, one envelope
Section titled “One call, one envelope”Two operations do the work, and both answer in the same shape: many providers in, one envelope out, every field in the same place whoever supplied it.
Search
Section titled “Search”Ask once; multiple independent search indexes answer in parallel, every result mapped to the same fields and tagged with the provider that found it.
Pick any subset per request — the slugs above are whatproviders.include takes in the call below.See how every provider's output is normalized →
curl -X POST https://router.telem.ai/v1/search \ -H "Authorization: Bearer $TELEM_API_KEY" \ -H "Content-Type: application/json" \ -d '{"user_input": {"query": "when was the International Space Station launched"}, "search": {"providers": {"include": ["exa", "brave"]}, "num_results": 3}}'The response — a real one, truncated
{ "status": "succeeded", "preprocessor_runs": [ { "preprocessor_name": "exa", "output_payload": { "tier": "default", "results": [ { "rank": 1, "url": "https://www.nasa.gov/history/20-years-ago-space-station-construction-begins/", "title": "20 Years Ago, Space Station Construction Begins - NASA", "summary": "Nov 20, 2018 ... The largest, most complex international construction project in space began..." } ], "latency_ms": 1471 } }, { "preprocessor_name": "brave", "output_payload": { "tier": "default", "results": [ { "rank": 1, "url": "https://en.wikipedia.org/wiki/International_Space_Station", "title": "International Space Station - Wikipedia", "summary": "The ISS is the political product of the development of international cooperation..." } ], "latency_ms": 598 } } ], "normalized_schema_version": 2}Same fields whichever index answered — you write one parser, and adding a provider never rewrites it.
Auto-routing
Section titled “Auto-routing”You do not have to pick the providers. Set auto_routing to "accuracy", and
Telem picks them for you. Telem finds the topic of each query, then sends the
query to the three providers that do best on that topic.
curl -X POST https://router.telem.ai/v1/search \ -H "Authorization: Bearer $TELEM_API_KEY" \ -H "Content-Type: application/json" \ -d '{"user_input": {"query": "papers on speculative decoding for LLM inference"}, "search": {"auto_routing": "accuracy", "num_results": 2}}'The response — a real one, truncated
{ "status": "succeeded", "routing": [ { "topic": "academic_papers", "score": 0.043288350105285645, "providers": ["perplexity", "brave", "exa"] } ], "preprocessor_runs": [ { "preprocessor_name": "perplexity", "output_payload": { "tier": "default", "results": [ { "rank": 1, "url": "https://arxiv.org/abs/2401.07851", "title": "Unlocking Efficiency in Large Language Model Inference: A Comprehensive Survey of Speculative Decoding", "summary": "[Submitted on 15 Jan 2024 (v1), last revised 4 Jun 2024 (this version, v3)]..." } ], "latency_ms": 1596 } }, { "preprocessor_name": "brave", "output_payload": { "tier": "default", "results": [ { "rank": 1, "url": "https://research.google/blog/looking-back-at-speculative-decoding/", "title": "Looking back at speculative decoding", "summary": "In 2022 we published \"Fast Inference from Transformers via Speculative Decoding\"..." } ], "latency_ms": 589 } }, { "preprocessor_name": "exa", "output_payload": { "tier": "default", "results": [ { "rank": 2, "url": "https://arxiv.org/abs/2211.17192", "title": "Fast Inference from Transformers via Speculative Decoding", "summary": "Fast Inference from Transformers via Speculative Decoding ... Inference from large autoregressive..." } ], "latency_ms": 2595 } } ], "normalized_schema_version": 2}The routing block shows the topic and the providers that Telem chose for
each query. A query with no clear topic runs on the default providers. The
installer asks if you want auto-routing, so the agent plugins can use it too.
How auto-routing works →
Then read the pages worth keeping. POST /v1/fetch takes a list of URLs and
returns one document each — page text, not raw HTML — through its own chain of
providers, the first that answers winning.
Walked in order until one answers — options.providers pins the chain to a subset. brightdata is pin-only: LinkedIn records, never walked by default.See how every fetch provider's output is normalized →
curl -X POST https://router.telem.ai/v1/fetch \ -H "Authorization: Bearer $TELEM_API_KEY" \ -H "Content-Type: application/json" \ -d '{"urls": ["https://en.wikipedia.org/wiki/International_Space_Station"], "options": {"tier": "default"}}'The response — one document per URL, truncated
{ "status": "succeeded", "preprocessor_runs": [ { "preprocessor_name": "web_fetch", "output_payload": { "fetched_results": [ { "url": "https://en.wikipedia.org/wiki/International_Space_Station", "status": "succeeded", "title": "International Space Station - Wikipedia", "content": "# International Space Station\n\nThe International Space Station (ISS) is a large space station assembled and maintained in low Earth orbit by a collaboration of five space agencies and their contractors...", "content_format": "markdown", "content_length": 184213, "http_status": 200, "provider": "firecrawl", "latency_ms": 2184 } ], "succeeded_count": 1, "failed_count": 0 } } ], "normalized_schema_version": null}One URL failing never fails the call — it comes back as its own failed row
with the reason, next to the documents that worked.
Route
One API across search providers — pick them per request, or let
auto-routing pick them per
query. Every index’s answers come back in one envelope.Fetch
Whole pages as readable content, not raw HTML — several URLs per call
through POST /v1/fetch.Observe
Every search and fetch lands in the console as a
live session trajectory with judged quality metrics.Reading this as an AI agent? /llms.txt indexes the whole docs;
/agents.md is your playbook.
Install for your agent
Add Telem to Claude Code, Codex, OpenCode, Pi, or OpenClaw — one page per host, with the exact install command.
API Reference
Explore the full HTTP API — endpoints, request/response shapes, and error codes.
For AI agents
A machine-readable playbook: when to reach for Telem, how to migrate an existing provider call, and the verified install commands.