Skip to content

Search and fetch

Fetch

Read whole pages by URL, several per call. The deployment sets the limits, such as the number of URLs per call: see Parameters & Configuration.

POST/v1/fetch

Send your API key as Authorization: Bearer. See Authentication. How each option works: Fetch parameters.

Request body

urlsstring[]
The pages to read, up to 5. One more is a 400 (over_url_cap).
options.content_formatstringdefault "markdown"one of markdown, text
The format of the page text: markdown or text.
options.inline_max_charsintegerdefault 20000at least 1
The most characters of page text for each page. A longer page comes back cut, with content_truncated: true.
options.inline_contentboolean
false returns every field except the page text.
options.tierstringdefault "default"one of minimalist, default, extended, max
Which fields each result has. See the fields per tier.
options.providersstring[]
The providers to try, in this order. Without it, Telem chooses. See Providers.
More fields: options.max_age_seconds, options.no_cache, session_id, metadata
options.max_age_secondsintegerat least 0
The oldest saved copy of a page that Telem may return, in seconds. 0 reads the page again.
options.no_cacheboolean
true reads every page again, and does not use a saved copy.
session_idstring (UUID)
Add the call to this session. Without it, Telem starts a new one.
metadataobject
Query lineage keys. Telem's plugins and integrations send them for you.

Response

200

statusstring
The state of the call, such as succeeded.
preprocessor_runs[]object[]
One run for each URL, in the order you sent them. batch_index is the URL's place in your list.
preprocessor_runs[].output_payload.fetched_results[]array
The result for that URL. Each has its own status: a URL that fails does not fail the call.
…fetched_results[].contentstring
The page text, in content_format.
…fetched_results[].content_truncatedboolean
true when the page text is longer than inline_max_chars.
…fetched_results[].providerstring
The provider that read the page.
…fetched_results[].errorobject or null
Why the URL failed, or null.
session_idstring (UUID)
The session that recorded the call. Send it back as session_id to add the next call to it.
interaction_idstring (UUID)
The ID of this call.
pinned_providersstring[] or null
Your options.providers list, in lower case and without duplicates, or null when you did not pin a chain.

created_at, completed_at: when Telem received the call and when it finished.

normalized_schema_version, routing: always null on a fetch.

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

StatusCodeWhen
400The request is not correct. error.code says why: missing_urls, invalid_url, over_url_cap, duplicate_urls, invalid_kind, invalid_session, invalid_request or unknown_provider.
401unauthorizedThe API key is missing or not valid.
402payment_requiredThe account cannot pay for the call. The message says why.
403The API key may not fetch pages, or the session_id belongs to another key.
409missing_snapshotsThe request names earlier context that Telem does not have. Nothing ran and nothing was billed. Send the request again with that context.
422invalid_requestA field has a value the API does not accept. error.param names the field.
502provider_unavailableYou named options.providers, and every URL failed before Telem reached the page. The call is recorded and billed. A dead link or a paywall is not this error: it is a result.
429Your key went over its requests-per-minute cap. Wait for the seconds in Retry-After, then try again.
504deadline_exceededNo fetch could start in time. It costs nothing. Try again after a short wait.

What each error means and what to do: Errors.

Was this page helpful?