BackSearch API

Overview

BackSearch answers one question no live search API can: “what did the web know on date X?” Every request carries an as_of date. Search returns only documents archived on or before that date, and fetch returns a page as it was captured at that time. The archive never moves, so the same query with the same as_of returns the same results forever. This is the same engine behind the BackSearchToolset you can declare in an environment, available here as a standalone HTTP API.

The cutoff gates on when a page was archived, not on the date the page claims for itself. A self-reported publish date is exactly the field a backdated crawl cannot trust, so gating on the capture is what guarantees nothing after the cutoff leaks in. Sources that carry an official date gate on that instead: SEC filings on their filing date, arXiv papers on the date each version was posted, and Wikipedia on the date of its monthly snapshot.

Base URL & authentication

https://search.openreward.ai

Authenticate with your OpenReward API key (or_...) in the x-api-key header. There is no separate credential to obtain.

export OPENREWARD_API_KEY="or_xxxxxxxx"

What is in the archive

Six corpora sit behind one endpoint. A search fans out across the corpora marked as default below; any corpus can also be named explicitly with the corpus field (see Corpus routing).

Source	`corpus`	Coverage	Gates on	Searched by default
News	`cc_news`	2025-12-01 → now, rolling	crawl date	yes
SEC filings (EDGAR)	`cc_sec`	2023-01-03 → now, rolling	filing date	yes
Wikipedia (English)	`cc_wiki`	2026-02-01 → now, monthly snapshots	snapshot date	yes
General web	`cc_web`	2025-06-12 → now, periodic crawl windows	crawl date	yes
Live captures	`cc_web_live`	rolling	crawl date	yes
arXiv	`cc_arxiv`	August 1991 → now, every version	version date	no

News is a continuous crawl of news domains. Each hit carries both the crawl date (what as_of gates on) and the article’s own publish date.
SEC filings are EDGAR filings including 10-Ks, 10-Qs, 8-Ks, 13Fs and Form 4s. They gate on the official filing date, and fetch returns the full text of the filing with tables rendered as markdown.
Wikipedia is a snapshot of English Wikipedia taken on the first of each month. A cutoff resolves to the newest snapshot on or before it, for both search and fetch.
General web is a broad crawl captured in periodic windows rather than continuously, starting June 2025. Fetch returns extracted text only.
Live captures are pages BackSearch fetched from the live web on demand to fill a coverage gap for a recent cutoff, then persisted with their capture date. See Recent cutoffs.
arXiv holds every paper since the first postings in August 1991, with each revision as its own capture. A cutoff between v1 and v2 returns v1. Fetch returns the LaTeX source of that version. arXiv is not part of the default fan-out because papers are noise on most non-academic queries; name it in corpus to search it.

Rolling sources are refreshed continuously and trail the present by a few days. An as_of before a source’s first capture simply returns nothing from that source rather than an error, so a run that silently finds no evidence is usually a date past the edge of the archive.

Pricing

Pay-as-you-go against your prepaid OpenReward balance, with no subscription.

Endpoint	Price
`POST /search`	$10 / 1,000 requests ($0.01 each)
`POST /fetch`	$2 / 1,000 requests ($0.002 each)

Only successful requests are billed. A search that errors, or a fetch that finds no capture on or before as_of (a 404), is not charged. When your balance is exhausted the API returns 402 Payment Required. Top up to continue.

POST /search

Hybrid lexical + semantic search over the archive, cut off at as_of.

Request body

Field	Type	Required	Description
`query`	string	yes	The search query. At least 2 characters. Queries made only of stopwords or whitespace return an empty `hits` list.
`as_of`	string	yes	Point-in-time cutoff, ISO `YYYY-MM-DD`. Only documents archived on or before this date (end of day, inclusive) are returned.
`start_date`	string	no	Lower bound of the window, ISO `YYYY-MM-DD`. Must be on or before `as_of`. Omit for no lower bound. Use it to ask for “the last week of news before the cutoff”.
`k`	integer	no	Number of hits to return, `1`–`100`. Default `10`.
`corpus`	string[]	no	Corpora to search, by name from the table above. Omit for the default fan-out. See Corpus routing.
`mode`	string	no	`hybrid` (default): BM25 and dense retrieval fused across the selected corpora. `dense`: vector retrieval only. `bm25`: lexical only over the news index; a legacy path that does not route across corpora and ignores `corpus`.
`lang`	string	no	ISO-639-1 language filter, e.g. `en`. Language is detected best-effort at ingest; documents with no detected language are excluded when a filter is set.
`site`	string	no	Restrict to hosts containing this string, e.g. `livemint.com` matches `www.livemint.com`.
`allowed_domains`	string[]	no	Only return hits whose host contains one of these strings. Mutually exclusive with `blocked_domains`.
`blocked_domains`	string[]	no	Exclude hits whose host contains one of these strings.

Corpus routing

With no corpus, a search fans out across every corpus marked as default: news, SEC filings, Wikipedia, general web and live captures.
Naming corpora replaces the default set rather than extending it. ["cc_arxiv"] searches arXiv alone; ["cc_arxiv", "cc_news"] searches arXiv and news.
An unrecognised corpus name is silently ignored, and matching is case-sensitive. A typo therefore returns ordinary default results rather than an error. Read each hit’s corpus field to confirm what served it.
Routing applies under hybrid and dense. Under bm25 the corpus field has no effect and hits come back with corpus: null.

Response

{
  "mode": "hybrid",
  "candidates": 5,
  "fallback": null,
  "hits": [
    {
      "url": "https://wtop.com/world/2025/12/bank-of-japan-raises-its-key-policy-rate-to-0-75-to-help-tame-inflation-and-support-the-yen/",
      "title": "Bank of Japan raises its key policy rate to 0.75% to help tame inflation and support the yen - WTOP News",
      "snippet": "TOKYO (AP) — Bank of Japan raises its key policy rate to 0.75% to help tame inflation and support the yen.",
      "crawl_date": "2025-12-20T15:13:41Z",
      "publish_date": "2025-12-18T10:24:31Z",
      "host": "wtop.com",
      "corpus": "cc_news",
      "duplicates": 0,
      "score": 0.0163
    }
  ],
  "time_taken_ms": 412.8
}

Field	Description
`hits[].crawl_date`	When the document was archived. This is what `as_of` gates on and is never later than your cutoff. For SEC filings it is the filing date, for arXiv the version date, for Wikipedia the snapshot date.
`hits[].publish_date`	The document’s own stated publish date, best-effort. May be `null`.
`hits[].corpus`	Which corpus produced the hit (`cc_news`, `cc_sec`, `cc_arxiv`, `cc_wiki`, `cc_web`, `cc_web_live`). `null` under `mode: "bm25"`.
`hits[].duplicates`	How many identical re-publications were collapsed into this hit (wire copy syndicated across many outlets). `0` means unique.
`hits[].score`	Rank-derived pseudo-score. Comparable within one response, not across responses.
`candidates`	Number of hits considered for the response. Equals the hit count in `hybrid` and `dense` modes.
`fallback`	`null` when served entirely from the archive. `"cache"`, `"corpus"` or `"live"` when a recent cutoff was filled from live captures; see below.
`time_taken_ms`	Server-side latency in milliseconds, from handler entry to response built. Excludes network time to you.

Example

curl
Python
arXiv only

curl -X POST https://search.openreward.ai/search \
  -H "x-api-key: $OPENREWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Bank of Japan policy rate decision",
    "as_of": "2026-01-15",
    "k": 5
  }'

import os, requests

resp = requests.post(
    "https://search.openreward.ai/search",
    headers={"x-api-key": os.environ["OPENREWARD_API_KEY"]},
    json={
        "query": "Bank of Japan policy rate decision",
        "as_of": "2026-01-15",
        "k": 5,
    },
)
for hit in resp.json()["hits"]:
    print(hit["crawl_date"], hit["corpus"], hit["title"], hit["url"])

curl -X POST https://search.openreward.ai/search \
  -H "x-api-key: $OPENREWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "attention is all you need transformer",
    "as_of": "2018-01-01",
    "k": 3,
    "corpus": ["cc_arxiv"]
  }'

Only versions posted on or before 2018-01-01 can appear (v1 through v5 of arXiv:1706.03762); the later revisions cannot.

hybrid handles paraphrase that lexical search misses. A query for “Eastern European territorial dispute escalation” surfaces Russia/Ukraine coverage even when those keywords are not present.

Recent cutoffs and live fallback

The rolling corpora trail the present by a few days, so a cutoff within the last two days can fall into a gap the archive has not filled yet. When such a search finds nothing usable, BackSearch fills it: first from the live-capture corpus (fallback: "corpus"), then from a cache of earlier live lookups ("cache"), and as a last resort from a live web provider ("live"). Pages found this way are stored in cc_web_live with their capture date, so the same query at the same cutoff is reproducible from then on. This path never engages for a cutoff older than two days. A backdated as_of is always answered from the frozen archive alone.

POST /fetch

Retrieve a page’s content as it was archived on or before as_of, the point-in-time counterpart to search.

Request body

Field	Type	Required	Description
`url`	string	yes	The page to fetch, as archived. Use the `https://` form; the API matches the URL as given and does not upgrade `http://`.
`as_of`	string	yes	Cutoff, ISO `YYYY-MM-DD`. Returns the latest capture on or before this date.
`summarize`	boolean	no	Default `true`: an LLM summary of the page is returned in `summary`, which adds a model call to the request. Set `false` for the raw extracted text only.
`prompt`	string	no	What the summary should focus on (with `summarize: true`). SEC filings and arXiv papers have analyst-style default prompts when this is omitted.
`max_chars`	integer	no	Cap on the returned `text` (and `html`), `200`–`1,000,000`. Omit for the full text. `summary` is never truncated.
`include_html`	boolean	no	Also return the raw archived HTML. Only news captures have HTML; other sources return `html: null`.

Response

{
  "url": "https://arxiv.org/abs/1706.03762v3",
  "crawl_date": "2017-06-20T05:20:02Z",
  "publish_date": "2017-06-20T05:20:02Z",
  "title": "Attention Is All You Need",
  "text": "The dominant sequence transduction models are based on complex recurrent or convolutional neural networks…",
  "summary": null,
  "summary_model": null,
  "truncated": true,
  "host": "arxiv.org",
  "html": null,
  "redirect": null,
  "math_fidelity": "latex",
  "version": 3
}

Field	Description
`url`	The archived URL that was served. For arXiv this is the versioned URL of the version selected by `as_of`.
`crawl_date`	When this capture was archived (filing date for SEC, version date for arXiv, snapshot date for Wikipedia). Never later than `as_of`.
`publish_date`	The page’s own stated publish date, best-effort. May be `null`.
`text`	Extracted text of the capture. Always populated, even with `summarize: true`.
`summary` / `summary_model`	The LLM summary and the model that wrote it. `null` when `summarize` is `false` or the summary call failed (the request still succeeds with `text`).
`truncated`	`true` when `text` (or `html`) was cut to `max_chars`.
`html`	Raw archived HTML when `include_html` is `true` and the source has it. Otherwise `null`.
`redirect`	Set when the archived response at `as_of` was a cross-host redirect: `{"to": "<url>", "status": 301}`. Fetch the `to` URL instead.
`math_fidelity`	arXiv only. `"latex"` means `text` is the author’s LaTeX source and equations are exact; `"pdf-text"` means it was extracted from a PDF and equations may be lossy. `null` for other sources.
`version`	arXiv only. Which version was served given `as_of`. `null` for other sources.

Per-source behaviour

Source	Accepted URLs	What `text` contains	Notes
News	The article URL as crawled	Extracted article text	HTML available with `include_html`.
SEC filings	`sec.gov/Archives/edgar/...` document URLs	Full filing text with tables as markdown	Gated on filing date. A filing filed after `as_of` returns `404`. Default summary is an analyst brief with the primary statements as markdown tables.
arXiv	`arxiv.org/abs/<id>`, `arxiv.org/pdf/<id>`, or a versioned `<id>vN`	LaTeX source of the selected version	An unversioned URL resolves to the newest version on or before `as_of`; a versioned URL pins that version. Before v1 was posted returns `404`.
Wikipedia	`en.wikipedia.org/wiki/<Title>`	Article text from the monthly snapshot	Resolves to the newest snapshot on or before `as_of`. A cutoff before the first snapshot returns `404`.
General web, live captures	The page URL as captured	Extracted text	No HTML is stored for these sources.

If there is no capture of the URL on or before as_of, the API returns 404 and does not bill the request. The detail string names the sources that were checked.

Example

curl
Python
With a summary

curl -X POST https://search.openreward.ai/fetch \
  -H "x-api-key: $OPENREWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://arxiv.org/abs/1706.03762",
    "as_of": "2017-07-01",
    "summarize": false,
    "max_chars": 20000
  }'

import os, requests

resp = requests.post(
    "https://search.openreward.ai/fetch",
    headers={"x-api-key": os.environ["OPENREWARD_API_KEY"]},
    json={
        "url": "https://arxiv.org/abs/1706.03762",
        "as_of": "2017-07-01",
        "summarize": False,
        "max_chars": 20000,
    },
)
page = resp.json()
print(page["version"], page["math_fidelity"], page["crawl_date"])
print(page["text"][:500])

curl -X POST https://search.openreward.ai/fetch \
  -H "x-api-key: $OPENREWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://wtop.com/world/2025/12/bank-of-japan-raises-its-key-policy-rate-to-0-75-to-help-tame-inflation-and-support-the-yen/",
    "as_of": "2026-01-15",
    "prompt": "What did the BoJ decide and why?"
  }'

summary holds the answer and summary_model names the model that wrote it.

as_of gates on the capture, not on the article’s stated publish date. A page first archived after your cutoff will not be returned even if it claims an earlier publish date. The one exception is sources with an official date (SEC filing date, arXiv version date, Wikipedia snapshot date), which gate on that.

Errors

Status	Meaning	Billed
`200`	Success.	yes
`400`	Policy error. Body is `{"result": false, "message": "...", "errorCode": N}`. `errorCode` `1` is an unparseable `url` on fetch; `2` is `allowed_domains` and `blocked_domains` set together on search.	no
`401`	No `x-api-key` header.	no
`402`	Balance exhausted. Top up to continue.	no
`403`	Invalid or disabled API key.	no
`404`	Fetch only. No capture of the URL on or before `as_of`.	no
`422`	Request validation failed: `query` under 2 characters, `k` outside `1`–`100`, `start_date` after `as_of`, `max_chars` outside `200`–`1,000,000`, or a malformed date. Body is a FastAPI `detail` list naming the field.	no
`502` / `503`	Transient. An index lookup failed or the arXiv version index was unavailable. Retry after a short delay; the document is not missing.	no

Other endpoints

Endpoint	Purpose
`GET /policy/domain_info?domain=<host>`	Domain preflight, authenticated like search. Returns `{"can_fetch": true}` or `{"can_fetch": false, "reason": "..."}` from the server-side domain policy. The SDK calls this before each fetch.
`GET /healthz`	Liveness check, no authentication.

Checking your usage

GET https://api.openreward.ai/v1/billing/api-usage returns metered search and fetch usage for the account behind your API key.

Query parameters

Field	Type	Description
`days`	integer	Window to report, 1–90. Default `30`.
`service`	string	Filter to `search` or `fetch`. Omit for both.
`granularity`	string	`total` (default) or `daily` for a per-day breakdown.

Response

{
  "since": "2026-08-16T00:00:00.000Z",
  "until": "2026-09-15T08:11:29.856Z",
  "byService": [
    { "service": "search", "requests": 1200, "units": "1200.000", "cost": "12.000000", "pendingRequests": 0 },
    { "service": "fetch",  "requests": 300,  "units": "300.000",  "cost": "0.600000",  "pendingRequests": 0 }
  ],
  "totals": { "requests": 1500, "cost": "12.600000", "pendingRequests": 0 }
}

curl
CLI

curl "https://api.openreward.ai/v1/billing/api-usage?days=30&granularity=daily" \
  -H "x-api-key: $OPENREWARD_API_KEY"

orwd usage                 # summary for the last 30 days
orwd usage --daily         # broken down by day
orwd usage --service search

Adding credits

To top up open your organization’s billing page at openreward.ai/<your-org>/billing (for example, openreward.ai/GeneralReasoning/billing).

Get started

Core Concepts

Making Environments

Advanced Environment Topics

Training

Evaluation

Harnesses

Sandbox Providers

Standalone APIs

Integrations

Rollouts

Deployment

Storage & Data

Overview

Base URL & authentication

What is in the archive

Pricing

POST /search

Request body

Corpus routing

Response

Example

Recent cutoffs and live fallback

POST /fetch

Request body

Response

Per-source behaviour

Example

Errors

Other endpoints

Checking your usage

Query parameters

Response

Adding credits

See also

​Overview

​Base URL & authentication

​What is in the archive

​Pricing

​POST /search

​Request body

​Corpus routing

​Response

​Example

​Recent cutoffs and live fallback

​POST /fetch

​Request body

​Response

​Per-source behaviour

​Example

​Errors

​Other endpoints

​Checking your usage

​Query parameters

​Response

​Adding credits

​See also

Overview

Base URL & authentication

What is in the archive

Pricing

POST /search

Request body

Corpus routing

Response

Example

Recent cutoffs and live fallback

POST /fetch

Request body

Response

Per-source behaviour

Example

Errors

Other endpoints

Checking your usage

Query parameters

Response

Adding credits

See also