> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Time Machine: search the web as of a past date

> Search and read the web as Keenable captured it at a past moment with query_time. Nothing published later can appear. Early Access.

> [!WARNING]
>
> The Time Machine API is in Early Access and can change before general availability.

Time Machine is its own API, separate from [search](https://docs.keenable.ai/api-reference/search.md) and [fetch](https://docs.keenable.ai/api-reference/fetch.md). It searches and reads the web as Keenable captured it at a past moment, given by `query_time`. Every result is a version of the page captured at or before `query_time`, so nothing published or edited later can appear. Use it to backtest agents and forecasts, to research what was known on a given date, or to build training datasets that can't see the future.

| Endpoint | What it does |
| - | - |
| `POST https://api.keenable.ai/v1/time_machine/search` | Searches the web as of `query_time` |
| `POST https://api.keenable.ai/v1/time_machine/fetch` | Reads one page as it was at `query_time` |

## Access

* Send your API key in the `X-API-Key` header.
* Time Machine must be turned on for your organization. If it isn't, every call returns `403` with `Feature not enabled`. To turn it on, email [support@keenable.ai](mailto:support@keenable.ai) with the `request_id` from that response, or ask your Keenable contact.
* Each search costs the same as a regular search, and each fetch the same as a regular fetch. If your organization has no balance left, calls return `402` with `Insufficient credits`.
* Most responses carry an `X-Request-Id` header. Include its value when you [report a problem](https://docs.keenable.ai/errors.md#report-a-problem).

## Quick start

Set your API key in the environment, then run the examples below.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
export KEENABLE_API_KEY=...   # your API key
```

**Search**: what was known about the WeWork IPO on 1 September 2019, a month before it was withdrawn.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -s -X POST "https://api.keenable.ai/v1/time_machine/search" \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "WeWork IPO", "query_time": "2019-09-01", "max_results": 3, "snippet_max_length": 200}'
```

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "query": "WeWork IPO",
  "query_time": "2019-09-01T00:00:00.000Z",
  "results": [
    {
      "title": "WeWork reveals massive $900 million loss in filing to go public",
      "url": "https://cnbc.com/2019/08/14/wework-releases-s-1-filing-for-ipo.html",
      "snippet": "rental company lined up to join a flurry of tech companies going public in 2019. WeWork, which rebranded to the We Company, is widely expected to go public as soon as next month. It was recently",
      "published_at": "2019-08-14T11:16:08Z",
      "acquired_at": "2019-08-25T03:19:43Z"
    },
    {
      "title": "WeWork reveals IPO filing",
      "url": "https://techcrunch.com/2019/08/14/wework-reveals-ipo-filing",
      "snippet": "WeWork, now known as The We Company, released its IPO prospectus Wednesday morning months after filing confidentially to go public. The company indicated plans to raise $1 billion in what is likely a",
      "published_at": "2019-08-14T11:24:51Z",
      "acquired_at": "2019-08-26T10:24:19Z"
    }
  ]
}
```

*(The response contains 3 results and a `usage` object; only 2 results are shown here.)*

**Search with filters**: the same call with `site` and `published_after`.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -s -X POST "https://api.keenable.ai/v1/time_machine/search" \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Uber IPO", "query_time": "2019-06-01T00:00:00Z", "site": "techcrunch.com",
       "published_after": "2019-04-01", "max_results": 3, "snippet_max_length": 200}'
```

The response has the same shape as the search above.

**Fetch**: one page as it was on 1 September 2019.

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -s -X POST "https://api.keenable.ai/v1/time_machine/fetch" \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.businessinsider.com/wework-ipo-we-company-history-founder-story-timeline-adam-neumann-2019-8",
       "query_time": "2019-09-01", "max_chars": 300}'
```

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "url": "https://businessinsider.com/wework-ipo-we-company-history-founder-story-timeline-adam-neumann-2019-8",
  "query_time": "2019-09-01T00:00:00.000Z",
  "acquired_at": "2019-08-23T12:47:36Z",
  "published_at": "2019-08-14T00:00:00Z",
  "title": "WeWork history, from Manhattan building to $47 billion valuation, IPO",
  "content": " WeWork’s $47 billion parent company, The We Company,  publicly filed its IPO paperwork on Wednesday. WeWork started as one office space in the SoHo neighborhood of New York City. Now it has nearly 800 locations open or coming soon in 124 cities around the world. The We Company is composed of WeW...",
  "truncated": true,
  "total_chars": 1132
}
```

*(The `usage` object is left out here.)*

Other `query_time` values return other versions of the same URL:

| `query_time` | Result |
| - | - |
| `2019-06-01` | `404`: no version had been captured yet |
| `2019-09-01` | The version captured on 2019-08-23, shown above |
| `2019-11-01` | The version captured on 2019-09-20, titled *"WeWork history, from single Manhattan building to global company, IPO"* |
| `2026-10-01` | The version captured on 2026-09-16, titled *"WeWork history, from single Manhattan building to pushing out its CEO"* |

## `query_time`

Both endpoints require `query_time`. The response echoes it in UTC ISO 8601 form, for example `2019-09-01T00:00:00.000Z`.

| Form | Example | Meaning |
| - | - | - |
| ISO 8601 with a time zone | `2019-09-01T12:00:00Z`, `2019-09-01T08:00:00-04:00` | That instant |
| ISO 8601 without a time zone | `2019-09-01T12:00` | That instant, in UTC |
| Date | `2019-09-01` | Midnight UTC at the start of that day |
| Unix epoch | `1567296000` (seconds) or `1567296000000` (milliseconds) | That instant |
| Relative | `30d` | 30 days before now. Units: `min`, `h`, `d`, `w`, `mo` (30 days), `y` (365 days) |

* `query_time` must not be in the future, and `now` is not accepted. For current results, use the regular [search API](https://docs.keenable.ai/api-reference/search.md).
* `query_time` must be a string, so quote epochs: `"1567296000"`.

## Search

`POST /v1/time_machine/search`, with the parameters as a JSON body.

### Request

**query** `string` *required*

What to search for, in words. A URL is rejected; to read a URL, use [fetch](#fetch).

**query\_time** `string` *required*

See [`query_time`](#query_time).

**site** `string`

Only results from this domain, e.g. `techcrunch.com`. A leading `www.` is optional.

**published\_after** `string`

Only pages published after this date. Accepts a date, an ISO 8601 timestamp, a Unix epoch, or a relative offset counted back from `query_time` (`7d` means 7 days before `query_time`).

**published\_before** `string`

Only pages published before this date. Same formats as `published_after`.

**max\_results** `integer` (default: 10)

How many results to return, from `1` to `50`.

**snippet\_max\_length** `integer`

Maximum snippet length in characters, 180–10,000. Without it, snippets are typically 500–3,500 characters.

**session\_id** `string`

Your own ID for grouping related requests. You can send it as the `X-Keenable-Session-Id` header instead.

Any other parameter returns `400` with `Unknown parameter(s)` and the list of supported parameters. If you send `safety_mode`, only `off` is accepted, and it changes nothing. `moderate` and `strict` return `400` with `Invalid parameter`, because Time Machine search has no safety filter. The `site:` operator inside `query` also works. The `acquired_after:` and `acquired_before:` operators are rejected. The `published_after:` and `published_before:` operators inside `query` take only absolute dates. A relative one, such as `published_after:7d`, is rejected, because there it would count back from now; use the `published_after` parameter, which counts back from `query_time`.

### Response

**query** `string`

Your query.

**query\_time** `string`

The `query_time` used, in UTC ISO 8601.

**results** `array`

Results, most relevant first.

**result**

**title** `string`

The page's title, from the captured version.

**url** `string`

The page's URL, normalized (for example, without `www.`).

**snippet** `string`

A relevant passage from the captured version.

**published\_at** `string`

The page's publication date in UTC ISO 8601. Absent when unknown.

**acquired\_at** `string`

When Keenable captured the version this result shows, in UTC ISO 8601. Always at or before `query_time`.

**warning** `string`

Present only when the API adjusted your query. For example, a query made only of `site:` operators is searched with the site's name as the search term.

**usage** `object`

What this call was billed: `sku` (`search.time_machine`), `amount` (1), `credits` (credits charged), `paid` (`true` when the credits came from your purchased balance, `false` when they came from your free allowance) and `credits_remaining` (what your organization has left after the call, left out if the balance couldn't be read). See [reading usage per call](https://docs.keenable.ai/credits.md#reading-usage-per-call).

## Fetch

`POST /v1/time_machine/fetch`, with the parameters as a JSON body. Returns the latest version of the page that Keenable stored at or before `query_time`. It never fetches the live page. Keenable doesn't have every older version of every page.

### Request

**url** `string` *required*

The page's URL. `www.` and non-`www.` forms return the same page, but `http://` and `https://` are different URLs.

**query\_time** `string` *required*

See [`query_time`](#query_time).

**max\_chars** `integer` (default: 50000)

Maximum content length, as a positive integer. Longer content is cut to fit and ends with `...` (left out when `max_chars` is 3 or less), so `content` is never longer than `max_chars`. The response then has `truncated` set to `true`.

**session\_id** `string`

Your own ID for grouping related requests. You can send it as the `X-Keenable-Session-Id` header instead.

### Response

**url** `string`

The page's URL, normalized.

**query\_time** `string`

The `query_time` used, in UTC ISO 8601.

**acquired\_at** `string`

When Keenable captured this version, in UTC ISO 8601.

**published\_at** `string`

The page's publication date in this version, in UTC ISO 8601. Absent when unknown.

**title** `string`

The page's title in this version. Absent when unknown.

**content** `string`

The page's text in this version.

**truncated** `boolean`

`true` when the text was longer than `max_chars` and `content` was cut.

**total\_chars** `integer`

The length of the full text in characters, before `max_chars` was applied.

**usage** `object`

What this call was billed: `sku` (`fetch.time_machine`), `amount` (1), `credits`, `paid` and `credits_remaining`, as in search.

If no version was captured at or before `query_time`, fetch returns `404` and the response suggests trying a later `query_time`.

## Errors

Errors use the [error body](https://docs.keenable.ai/errors.md#error-body) shared by all endpoints. `error` is a short title, `code` is a stable machine-readable code, and `fix` says what to do next. Branch on `code`, not on the text of `error` or `message`. A call that returns an error is not billed, and its response carries no `usage`.

| Status | `error` | When |
| - | - | - |
| 400 | `Missing required parameter` | `query`, `url` or `query_time` is missing, or `query_time` is `now`. |
| 400 | `Invalid parameter` | `query_time` is malformed, in the future, or not a string; a value is out of range; or `query` contains a rejected operator. |
| 400 | `Bad request` | An unknown parameter, a URL as a search query, an unparseable fetch URL, or a malformed `published_after` or `published_before`. |
| 401 | `Missing authentication` or `Authentication failed` | The API key is missing or invalid. |
| 402 | `Insufficient credits` | Your organization has no balance left. |
| 403 | `Feature not enabled` | Time Machine is not enabled for your organization. |
| 403 | `Upstream forbidden` | Fetch: the stored version is a bot-check page, not the page itself. |
| 404 | `Not found` | Fetch: no version was captured at or before `query_time`. |
| 405 | `Method not allowed` | A method the endpoint doesn't take, such as `GET`. The `Allow` header lists the methods it takes. |
| 422 | `Unprocessable entity` | Fetch: the stored version has no usable text, for example an empty page or a login wall. |
| 429 | `Rate limit exceeded` | Your organization's requests-per-second limit was exceeded. |
| 5xx | Varies | A transient failure. Retry with backoff. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.