Skip to main content
The Time Machine API is in Early Access and can change before general availability.
Time Machine is its own API, separate from search and fetch. 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.

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 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.

Quick start

Set your API key in the environment, then run the examples below.
Search: what was known about the WeWork IPO on 1 September 2019, a month before it was withdrawn.
(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.
The response has the same shape as the search above. Fetch: one page as it was on 1 September 2019.
(The usage object is left out here.) Other query_time values return other versions of the same URL:

query_time

Both endpoints require query_time. The response echoes it in UTC ISO 8601 form, for example 2019-09-01T00:00:00.000Z.
  • query_time must not be in the future, and now is not accepted. For current results, use the regular search API.
  • query_time must be a string, so quote epochs: "1567296000".
POST /v1/time_machine/search, with the parameters as a JSON body.

Request

string
required
What to search for, in words. A URL is rejected; to read a URL, use fetch.
string
required
string
Only results from this domain, e.g. techcrunch.com. A leading www. is optional.
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).
string
Only pages published before this date. Same formats as published_after.
integer
default:"10"
How many results to return, from 1 to 50.
integer
Maximum snippet length in characters, 180–10,000. Without it, snippets are typically 500–3,500 characters.
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

string
Your query.
string
The query_time used, in UTC ISO 8601.
array
Results, most relevant first.
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.
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.

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

string
required
The page’s URL. www. and non-www. forms return the same page, but http:// and https:// are different URLs.
string
required
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.
string
Your own ID for grouping related requests. You can send it as the X-Keenable-Session-Id header instead.

Response

string
The page’s URL, normalized.
string
The query_time used, in UTC ISO 8601.
string
When Keenable captured this version, in UTC ISO 8601.
string
The page’s publication date in this version, in UTC ISO 8601. Absent when unknown.
string
The page’s title in this version. Absent when unknown.
string
The page’s text in this version.
boolean
true when the text was longer than max_chars and content was cut.
integer
The length of the full text in characters, before max_chars was applied.
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 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.