File a run under a project (or unfile it)

PATCH

/v1/runs/{id}

const url = 'https://api.hyperresearch.ai/v1/runs/example';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"project_id":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://api.hyperresearch.ai/v1/runs/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "project_id": "example" }'

Sets project_id; null unfiles the run. Allowed while the run is queued or terminal; a run that is running, paused or blocked is a 409 run_not_filable. Filing a run also RETAGS the notes it wrote: project:<id> is added (and the previous project’s tag removed), so the run’s evidence appears under the project’s Sources and Vault and is reusable by that project’s later runs. notes_retagged on the response says how many notes moved; 0 means the run wrote none, or the vault could not be reached — the run itself is filed either way.

Authorizations

bearerAuth
runs:write
sessionCookie
runs:write

Parameters

Path Parameters

required

string

>= 3 characters <= 64 characters

Request Body^required

application/json

object

project_id

required

string | null

>= 3 characters <= 64 characters

Example^generated

{
  "project_id": "example"
}

Responses

200

Run

application/json

object

required

string

project_id

required

string | null

query_preview

required

string | null

display_title

required

string | null

status

required

string

tier

required

string

profile

required

string

price_cents

required

integer

billed

required

boolean

included

required

True when an included (trial) run covered this run, so it metered at $0. The server’s answer to “Included in trial” — never inferred from price_cents. Alias of included_in_trial.

boolean

included_in_trial

required

Same value as included, spelled the way the console reads it.

boolean

trial_tier

required

Which included-run allowance was claimed (light/full), or null.

string | null

complimentary

True when an operator grant comped this run (0041). The same field and the same value GET /v1/runs/{id} publishes, so a list row can print “Complimentary” beside the price.

boolean

charged_cents

required

What the billing ledger metered for this run, refunds included. 0 for a trial-covered run; null when no ledger row exists yet — which is NOT the same as zero.

integer | null

sources_fetched

required

The same number the run detail reports in progress.sources_fetched. Null until the run has reported one. Also in counters.

integer | null

notes_written

required

integer | null

counters

required

Everything a list row counts, in one place, cached from the RunAgent: the same numbers GET /v1/runs/:id reports in progress, a few seconds behind at most, so a list card never has to fetch the run to show them (E2E2-13/E2E2-24). sources_fetched/notes_written above are the same numbers, kept flat for existing clients.

object

sources_fetched

required

Sources this run KEPT; the same number progress.sources_fetched and the counters stream event report (E2E4-02).

integer | null

notes_written

required

integer | null

candidates_seen

required

Candidates considered, kept or not. Always >= sources_fetched when both are known.

integer | null

fetch_attempts

required

Physical fetch attempts — requests that actually went out. A vault lookup is not one, so this can be lower than candidates_seen (E2E7-02).

integer | null

sources_listed

required

DEPRECATED spelling of candidates_seen, emitted in step with it. Read candidates_seen.

integer | null

steps_done

required

Steps finished. Step progress lives in the run’s Durable Object and this list will not open one per row (E2E2-24), so the RunAgent writes it through to the control row on every step transition (0026). NULL for a run that has not reported one yet — a client that finds it null can still derive the scale from the tier.

integer | null

steps_total

required

Steps this run’s tier executes, from the same write-through. NULL when the run has not reported one yet.

integer | null

step_id

required

The step this run is on, cached from the RunAgent; null when it is not running.

string | null

step_name

required

That step in human words (the shared step → name map), or null.

string | null

step_detail

The unit inside that step, in customer words: “Chapter 2 of 4 · Depth investigation”, “Writing section 3 of 9”. The same string GET /v1/runs/{id} reports as step.detail, cached from the RunAgent (0035). Null on a flat run and once the step stops.

string | null

chapters_total

How many chapters this run’s plan has. A count of the PLAN, so it outlives the run and a finished Deep row still says how many chapters the customer got. Null means the run is not chaptered (or settled before the column existed) — never zero.

integer | null

report_words

required

Word count of the finished report; null while there is no report.

integer | null

blocked_on

required

One customer-safe sentence saying what a blocked run is waiting for a person to do, and null on every other status. The same value GET /v1/runs/{id} reports, so a list row can prompt for a resume without fetching the run.

string | null

blocked_code

The machine gate id behind blocked_on — step:<id>:<check>, verify:<check>, fetch_budget, model_budget or provider:<name>. Branch on this; print blocked_on.

string | null

wait_reason

Why a blocked run is waiting on US rather than on a person: it is clearing the condition by itself and will carry on with no action from the caller, and nothing has been charged. Present only while a run is waiting; absent or null on every other run, including a block that does need the customer to act. Branch on its PRESENCE, not on the class.

string | null

Allowed values: provider_billing provider_rate_limit provider_outage platform_capacity platform_transient vault_unavailable

recovering

Present, non-null, while a running/blocked run is being RECOVERED: our infrastructure interrupted it and we are resuming it from where it stopped, on the same run id, at no extra charge (Deep automatic recovery). Absent or null on every other run. While set, wait_reason is null and blocked_on is not a gate: the run needs nothing from anyone. Branch on its PRESENCE.

object

attempt

required

Which automatic recovery this is (1, 2, 3), or null while a stalled run is being handed over and the attempt is not yet claimed.

integer | null

failure_reason

required

Why this run ended badly, in one customer-safe sentence; null for a healthy run. For a blocked run this is blocked_on, matching the run status view. The raw text is failure_detail on the run detail, owner/admin only.

string | null

aborted_by

required

The user id that asked for the abort, or null for a run nobody stopped, a run stopped by an unattributed API key, or one stopped before this field existed. Published so a client can say “Stopped by you.” on its own terms rather than inferring it from the sentence; failure_reason is already narrowed for the caller.

string | null

failure_request_id

required

string | null

channel

required

string

dry_run

required

True when this run was a DRY RUN: the orchestration was real but the model provider and the fetch/search vendors were mocked, so the report is synthetic and the price is $0. Server truth (the run’s dry_run channel), never inferred from a zero price — a trial run and a fixture run are also $0 and are not dry. Always false in production, where dry runs cannot be created.

boolean

created_at

required

string

started_at

required

string | null

finished_at

required

string | null

duration_ms

required

Wall time from start (or creation) to finish; null while the run is unfinished. Settled in the same statement that writes finished_at, and carried on the terminal stream event, so a watching page and a reloaded one never differ (E2E8-13).

integer | null

version_of

required

The newest run asking the same question, or null when this run IS that run. Label a row “Earlier version” if and only if this is set. Grouped by normalised question text, or by an explicit rerun parent — never by project (E2E8-10).

string | null

version_group

Stable key for the version group, so a client can bucket a page in one pass.

string

receipt_summary

required

What this report’s own verification receipt came to, in four counts — so a row or a card can show that a report needs a second look without opening it (E2E10-07). Null means no receipt is known for this run (it did not produce one, or it finished before the counts were stored); null is NOT a pass.

object

passed

required

Checks that ran and met their bar. A warning is NOT a pass (E2E8-01).

integer

warning

required

Checks that ran and recorded a finding below our own target. Informational; see attention for what a reader should act on.

integer

failed

required

Checks that ran and did not meet their bar.

integer

skipped

required

Checks with nothing to judge (“not applicable”). Counted apart from the three above.

integer

attention

Findings a reader should act on before relying on the report: cited statements that say more than their sources support (above 3 and 3% of those checked), a chapter without its full research pass, a retracted source, or final checks that did not run. Absent on a summary cached before this field existed.

integer

notes_retagged

required

Vault notes moved to the new project scope by this call.

integer

Example

{
  "wait_reason": "provider_billing"
}

Headers

RateLimit-Policy

string

Example

"reads";q=60;w=60

The quota policy this request was counted against (draft-ietf-httpapi-ratelimit-headers): "<bucket>";q=<requests>;w=<window seconds>, e.g. "reads";q=60;w=60. Buckets: reads 60/min, status 600/min, creates 10/min, writes 20/min per credential; public 300/min per network on keyless routes.

RateLimit

string

Example

"reads";r=57;t=41

Remaining quota in the current window: "<bucket>";r=<remaining>;t=<seconds until reset>, e.g. "reads";r=57;t=41.

X-RateLimit-Limit

integer

Requests allowed per window in this bucket (legacy form of RateLimit-Policy).

X-RateLimit-Remaining

integer

Requests left in this window (legacy form of RateLimit).

X-RateLimit-Reset

integer

Unix time (seconds) when the window resets.

X-RateLimit-Bucket

string

Which bucket counted the request: reads, status, creates, writes or public.

400

Invalid request

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

Allowed values: missing_api_key malformed_api_key invalid_api_key api_key_expired api_key_revoked account_suspended workspace_unavailable session_expired insufficient_scope signup_closed role_not_permitted membership_required csrf_required csrf_invalid origin_not_allowed https_required key_route_restricted tier_not_allowed runs_paused invalid_body invalid_query invalid_path query_too_short query_not_research query_too_long query_refused invalid_title invalid_brief invalid_must_read invalid_research_brief invalid_time_window invalid_pulse invalid_metadata invalid_tier too_many_required_headings sources_max_above_ceiling reuse_scope_needs_project invalid_webhook_url metadata_too_large invalid_settings invalid_step unsupported_tier tier_not_offered plan_not_offered provider_excluded dry_run_not_enabled invalid_dry_run_fault chaos_faults_not_enabled invalid_chaos_fault gone run_not_found key_not_found workspace_not_found webhook_not_found artifact_not_found note_not_found escalation_not_found source_not_found connection_not_found project_not_found answer_not_found account_not_found feature_not_enabled idempotency_key_reuse idempotency_in_flight run_not_resumable run_not_finish_resumable run_finish_resume_exhausted run_recovering rerun_not_platform platform_rerun_taken run_not_clarifying result_not_ready workspace_not_empty turnstile_invalid turnstile_replayed demo_daily_limit demo_receipt_invalid demo_disabled user_not_found member_not_found member_exists last_owner cannot_self_elevate workspace_limit invitation_not_found invitation_expired invitation_email_mismatch account_mismatch ip_not_allowed chat_keys_retired project_name_taken project_archived run_not_filable confirmation_mismatch ownership_transfer_required account_deleting export_cooldown migration_pending rate_limit_exceeded concurrency_limit spend_cap_exceeded trial_exhausted payment_method_required payment_disputed card_hold_unavailable card_required insufficient_balance wallet_frozen topup_amount_invalid topup_daily_limit answers_capacity platform_capacity daily_run_limit internal_budget orchestrator_unavailable source_unconfigured source_rate_limited source_upstream_unavailable deployment_misconfigured not_implemented pdf_unavailable internal_error

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

401

Authentication failed

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

403

Insufficient scope or plan

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

404

Not found

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

409

The run is mid-flight, or the target project is archived

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

429

Rate limited or over quota

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying. Always present on a 429.

RateLimit-Policy

string

Example

"reads";q=60;w=60

RateLimit

string

Example

"reads";r=57;t=41

Remaining quota in the current window: "<bucket>";r=<remaining>;t=<seconds until reset>, e.g. "reads";r=57;t=41.

X-RateLimit-Limit

integer

Requests allowed per window in this bucket (legacy form of RateLimit-Policy).

X-RateLimit-Remaining

integer

Requests left in this window (legacy form of RateLimit).

X-RateLimit-Reset

integer

Unix time (seconds) when the window resets.

X-RateLimit-Bucket

string

Which bucket counted the request: reads, status, creates, writes or public.

500

Internal error

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request authentication permission not_found rate_limited quota_exceeded budget_blocked conflict provider_unavailable internal

code

required

string

message

required

string

param

string

retry_after

integer

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "missing_api_key",
    "request_id": "req_01J9ZQ7V6H0000000000000000"
  }
}

File a run under a project (or unfile it)

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Examplegenerated

Responses

200

Example

Headers

Example

Example

400

Example

401

Example

403

Example

404

Example

409

Example

429

Example

Headers

Example

Example

500

Example

Request Body^required

Example^generated