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
urls- The pages to read, up to 5. One more is a
400(over_url_cap). options.content_format- The format of the page text:
markdownortext. options.inline_max_chars- The most characters of page text for each page. A longer page comes back cut, with
content_truncated: true. options.inline_contentfalsereturns every field except the page text.options.tier- Which fields each result has. See the fields per tier.
options.providers- 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_seconds- The oldest saved copy of a page that Telem may return, in seconds.
0reads the page again. options.no_cachetruereads every page again, and does not use a saved copy.session_id- Add the call to this session. Without it, Telem starts a new one.
metadata- Query lineage keys. Telem's plugins and integrations send them for you.
Response
200
status- The state of the call, such as
succeeded. preprocessor_runs[]- One run for each URL, in the order you sent them.
batch_indexis the URL's place in your list. preprocessor_runs[].output_payload.fetched_results[]- The result for that URL. Each has its own
status: a URL that fails does not fail the call. …fetched_results[].content- The page text, in
content_format. …fetched_results[].content_truncatedtruewhen the page text is longer thaninline_max_chars.…fetched_results[].provider- The provider that read the page.
…fetched_results[].error- Why the URL failed, or
null. session_id- The session that recorded the call. Send it back as
session_idto add the next call to it. interaction_id- The ID of this call.
pinned_providers- Your
options.providerslist, in lower case and without duplicates, ornullwhen 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
| Status | Code | When |
|---|---|---|
400 | The 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. | |
401 | unauthorized | The API key is missing or not valid. |
402 | payment_required | The account cannot pay for the call. The message says why. |
403 | The API key may not fetch pages, or the session_id belongs to another key. | |
409 | missing_snapshots | The request names earlier context that Telem does not have. Nothing ran and nothing was billed. Send the request again with that context. |
422 | invalid_request | A field has a value the API does not accept. error.param names the field. |
502 | provider_unavailable | You 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. |
429 | Your key went over its requests-per-minute cap. Wait for the seconds in Retry-After, then try again. | |
504 | deadline_exceeded | No fetch could start in time. It costs nothing. Try again after a short wait. |
What each error means and what to do: Errors.