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-Keyheader. - Time Machine must be turned on for your organization. If it isn’t, every call returns
403withFeature not enabled. To turn it on, email support@keenable.ai with therequest_idfrom 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
402withInsufficient credits. - Most responses carry an
X-Request-Idheader. Include its value when you report a problem.
Quick start
Set your API key in the environment, then run the examples below.usage object; only 2 results are shown here.)
Search with filters: the same call with site and published_after.
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_timemust not be in the future, andnowis not accepted. For current results, use the regular search API.query_timemust be a string, so quote epochs:"1567296000".
Search
POST /v1/time_machine/search, with the parameters as a JSON body.
Request
What to search for, in words. A URL is rejected; to read a URL, use fetch.
See
query_time.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).Maximum snippet length in characters, 180–10,000. Without it, snippets are typically 500–3,500 characters.
Your own ID for grouping related requests. You can send it as the
X-Keenable-Session-Id header instead.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
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.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
The page’s URL.
www. and non-www. forms return the same page, but http:// and https:// are different URLs.See
query_time.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.Your own ID for grouping related requests. You can send it as the
X-Keenable-Session-Id header instead.Response
What this call was billed:
sku (fetch.time_machine), amount (1), credits, paid and credits_remaining, as in search.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.