Skip to main content
POST
Read up to 20 pages in one call and get one result for each URL, in the order you sent them. Each result is the page as markdown, or what you asked for instead: an answer to a prompt, a JSON object that matches your schema, the page’s links and its images. The API reference covers the base URL, authentication and the limits every endpoint shares. The SDKs call this endpoint from fetch. See SDK methods.

How a call works

  • Keenable reads the pages in parallel. results has one entry per URL you sent, in the same order: results[i] is for urls[i].
  • Each entry is either a page or {"url": ..., "error": {...}}, where url is the URL as you sent it and error says why that page failed. A page that fails doesn’t fail the call, and the call returns 200.
  • Keenable checks every URL before it reads any page. A URL listed twice in one call, or one that isn’t a valid http or https URL or runs over 8,192 characters, fails the whole call with 400 and param set to urls[i]. A URL that points to a private or internal address fails the whole call with 403 and private_url_not_allowed, as on GET /v1/fetch. Nothing is read or billed. A repeated URL is refused so that no page is read and billed twice in one call.
  • The whole call fails, with no results, when the request itself can’t run: an invalid body or URL, a missing or wrong API key, a balance that can’t cover the call or the rate limit. It also fails when every URL fails with the same 400, 401, 402 or 403 error, such as a content.schema that Keenable can’t use. The call then returns that error. See Errors.
  • A call counts as one request toward your organization’s rate limit, however many URLs it has.
  • Each page read is billed at the fetch price, so a call that reads 20 pages costs 20 times one page. Each page is billed as a GET /v1/fetch of that URL would be, failed pages included. Before any page is read, your free allowance and balance must cover every URL in the call. If they don’t, the call returns 402 with insufficient_credits and reads nothing.

What each page returns

content sets what each page carries. Every field in it is optional. Every page also carries image, its main image, and favicon, the site’s icon. You don’t need to ask for them. Either is null when the page has none. prompt works the same way as the prompt parameter of GET /v1/fetch. Write it as an instruction or a question about the page, such as List the pricing tiers with their monthly prices. schema takes a JSON Schema whose root has "type": "object". If the page is read but the answer can’t be made, the page still comes back with answer_error in place of structured. answer_error.code is one of summary_input_too_long, summary_no_content, summary_truncated, summary_schema_mismatch and summary_failed.

Where pages come from

By default, Keenable returns its indexed copy of a page if it has one, whatever its age, and reads the page live from its source otherwise. retrieval.max_age_hours changes that: max_age_hours takes a number of hours from 0 to 720 (30 days). Fractions work: 0.25 is 15 minutes. When you send max_age_hours, each page has stale. It’s true when the page you got is an indexed copy older than max_age_hours, because the live read failed or Keenable couldn’t use what it read. Otherwise it’s false.

Billing

  • Each page that comes back without an error is billed as one fetch at the standard fetch prices: fetch for Keenable’s indexed copy, fetch.live for a live read.
  • A page that fails is treated like a failed GET /v1/fetch call. See What isn’t billed.
  • prompt, schema, links and images don’t change the price.
  • Each page carries its own usage object, the same as a GET /v1/fetch response. See Balance and usage.

API key

POST /v1/fetch needs an API key. There is no keyless version: a call without a key returns 401 with missing_api_key. Send the key in X-API-Key or as Authorization: Bearer. See Authentication.

Limits

Request

Send a JSON object with Content-Type: application/json. Only urls is required. A field that isn’t listed here, at the top level or inside content or retrieval, returns 400 with unknown_parameter, and the message lists the supported fields. To group the calls of one agent task, send the X-Keenable-Session-Id header.
string[]
required
The pages to read: 1 to 20 absolute http or https URLs, each up to 8,192 characters and each listed once. Send urls even for one page. If urls is missing, the API returns 400 with missing_parameter. If it isn’t an array of 1 to 20 non-empty strings, the API returns 400 with invalid_parameter. If one URL is listed twice, isn’t a valid URL or is too long, the API returns 400 with invalid_parameter and param set to that entry, such as urls[2], and reads no page. If one points to a private or internal address, the API returns 403 with private_url_not_allowed and param set to that entry, and reads no page.
object
What each page carries. See What each page returns.
object
Where each page is read from. See Where pages come from.

Response

A 200 returns {"results": [...]}, with one entry per URL in urls, in the same order.
object[]
required
Each entry is a page, or an error for that URL.
This response shows the shape of a call with two URLs: one page, with its text left out, and one URL that failed:
Example response · shape only

Errors

These statuses fail the whole call. Errors for single pages come back in results. Every error has the same shape as on the other endpoints, with error, message, code, fix and retryable.

Move from GET /v1/fetch