runs

Create a run

Validates the request, checks the tier against the plan, the workspace concurrency limit and the account spend cap, fixes the price, writes the D1 index row, and starts the research-run Workflow.

post/v1/runs

Request

Base URL: https://api.hyperresearch.ai
URL: https://api.hyperresearch.ai/v1/runs
Auth: one of:
- HTTP bearer
- API key in cookie hr_session

Headers

idempotency-keystring

Request body

querystring required

tier'light' | 'premier'

The tier to run at: light ($9, one focused question or a narrow topic) or premier ($49, shown as "Deep" - a broader question across several research sections). Omitted, it is light. brief, full, dissertation and auto are not offered and are refused with 400 tier_not_offered.

clarify'ask' | 'auto' | 'off'

What to do about an ambiguous question, decided BEFORE anything is reserved or charged. ask assesses the question and, when it earns it, holds the run at clarifying with at most three questions for a person to answer at POST /v1/runs/{id}/clarify; left unanswered for 30 minutes it starts by itself on the stated assumptions (or closes without charge if it cannot be admitted then). auto assesses but never waits: the run starts immediately on those assumptions, which its report then names. Under ask and auto a query with nothing to research in it (a greeting, a test string) is held at clarifying and asked what to research; unanswered, it closes without charge. off is a hard bypass: no assessment and no interview of any kind — the run starts at once on the query as written, and a query with nothing to research in it is refused with 400 query_not_research instead of being held. Omitted, a console run defaults to ask and every other channel to auto, unless the workspace sets clarify_default.

profile'value' | 'speed' | 'quality'

project_idstring

File this run under a project in the same workspace. The run’s notes are tagged project:<id> and vault reuse is scoped to that tag. Omit for an unfiled run.

webhook_urlstring uri

metadataobject

Example request

{
  "query": "What changed in EU AI Act enforcement in 2026?",
  "tier": "light",
  "clarify": "auto",
  "levers": {
    "purpose": "decide",
    "report_language": "zh",
    "reader_expertise": "expert"
  },
  "vault": {
    "reuse_scope": "workspace"
  },
  "project_id": "proj_01J9ZQ7V6H0000000000000000"
}

Response

Run queued

idstring required

status'queued' | 'clarifying' | 'aborted' required

clarifying when the question was ambiguous enough to be worth asking about, or was not a research question at all. The run exists at its final id and is waiting at POST /v1/runs/{id}/clarify; nothing has been reserved or charged, so price_cents is null. aborted is only ever answered by POST /v1/runs/{id}/clarify, for an interview that ran out of rounds without finding a research question: that run started nothing, reserved nothing and claimed no included run.

price_centsinteger nullable required

events_urlstring required

created_atstring required

Example response

{
  "id": "run_01J9ZQ7V6H0000000000000000"
}

Changes

No recorded changes to this operation across all 1 revision of this API.