DocsAPIQueries

Queries

Send a question, wait for the run to finish, and get back the answer, the sources it was written from, and a request_id.

01Endpoint

POSThttps://researchanything.ai/api/query

Authenticate with an API key, as Authorization: Bearer ra-… or X-Api-Key: ra-…. See Authentication.

Each call starts a new run on RA-Lite with automatically chosen sources, and uses one research run from your plan's monthly allowance. See What a run uses.

02Request

The body is a JSON object with one field.

JSON

{
  "query": "Compare GDPR and CCPA on the right to have personal data deleted."
}

Parameters

Param	Type	Required	Description
query	string	yes	The question to research, 1 to 2,000 characters. A specific question gets a more useful answer than a keyword.

The body is validated against a schema that also has model, depth_mode, source_mode, project_id, user_id and preferences fields. This endpoint ignores all of them, but a value outside what the schema allows (for example an unknown model) still fails validation with 422. Leave them out. Fields the schema does not know are ignored.

03Response

Once the run has ended, the endpoint returns the response envelope.

Field	Type	Description
request_id	string	A UUID for this call. It identifies the run in the Console's usage list and run timeline.
status	string	`ok` when the run completed, `error` when any part of it failed.
answer	string or null	The answer in Markdown, citing sources inline as `[S1]`, `[S2]` and so on. `null` when `status` is `error`.
sources	array	The sources the run read closely and wrote from, at most five. See Sources.
usage.latency_ms	number	How long the run took, in milliseconds.
usage.tokens_in	number	An estimate of the query's size in tokens (its length in characters divided by four). Not a count of model tokens.
usage.tokens_out	number	The same estimate for the answer.
errors	array	`{ "code", "message" }` objects. Empty on success. See Errors.

Citation markers

A marker [Sn] in answer refers to the n-th entry of sources, counting only entries without an analysis_error field. When every source was analysed, which is the usual case, [S1] is sources[0], [S2] is sources[1], and so on.

Sources

Each entry in sources is an object. These fields are the ones to rely on; others are present and may change.

Field	Type	Description
id	string	The source's id within the run. It matches the `id` on `source` stream events.
title	string	Page or paper title.
url	string	Where the source was read.
domain	string	The URL's site.
snippet	string or null	The search result's excerpt.
author	string or null	Author, when the page states one.
publish_date	string or null	Publication date, when the page states one.
citations	object	Ready-made citations for the source, keyed `mla`, `apa`, `chicago`, `ieee`, `harvard` and `bibtex`.
scores	object	The ranking scores used to choose the source: `authority`, `relevance`, `recency`, `reputability` and a combined `final`.
analysis	object	What the run took from the source: `executive_summary`, a longer `markdown` summary, a `relevance` judgement and the `quotes` it relied on.
analysis_error	string	Present only when the source could not be analysed. Such a source was not used to write the answer.

Status codes

Code	Meaning
200	The run ended. Check `status`: it is `error` if the run failed part-way.
401	`missing_api_key` or `invalid_api_key`.
403	`key_inactive`: the key has been revoked.
422	The body failed validation: missing or empty `query`, `query` over 2,000 characters, or invalid JSON. The body is `{ "detail": [ … ] }`, not the envelope.
429	`quota_exceeded`: this month's research runs are used up.
503	`identity_db_unavailable`: the key could not be checked. Retry shortly.

Timing

The endpoint answers only when the run has ended, and a run searches, reads and analyses sources before it writes. Give your HTTP client a timeout of several minutes. To show progress while a run works, or to get the request_id before it finishes, use streaming.

Each call is a new run. Sending the same query again starts another run and uses another research run from your allowance.

04Examples

cURL

curl https://researchanything.ai/api/query \
  -H "Authorization: Bearer $ESSARION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Compare GDPR and CCPA on the right to have personal data deleted."}'

Node — fetch

Node

async function ask(question) {
  const res = await fetch("https://researchanything.ai/api/query", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.ESSARION_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: question }),
  });

  const body = await res.json().catch(() => ({}));
  if (!res.ok || body.status !== "ok") {
    const err = body.errors?.[0];
    throw new Error(`ResearchAnything ${res.status}: ${err?.code ?? "unknown"} ${err?.message ?? ""}`);
  }
  return body;
}

const result = await ask("Compare GDPR and CCPA on the right to have personal data deleted.");
console.log(result.answer);

Python — requests

Python

import os
import requests

def ask(question: str) -> dict:
    resp = requests.post(
        "https://researchanything.ai/api/query",
        headers={"Authorization": f"Bearer {os.environ['ESSARION_KEY']}"},
        json={"query": question},
        timeout=600,
    )
    body = resp.json()
    if resp.status_code != 200 or body.get("status") != "ok":
        raise RuntimeError(f"{resp.status_code}: {body.get('errors') or body.get('detail')}")
    return body

result = ask("Compare GDPR and CCPA on the right to have personal data deleted.")
print(result["answer"])

05Example response

An abbreviated 200 response. Source objects are cut down to a few fields.