runs

File a run under a project (or unfile it)

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.

patch/v1/runs/{id}

Request

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

Path parameters

idstring required

Request body

project_idstring nullable required

Response

Run

idstring required
project_idstring nullable required
query_previewstring nullable required
display_titlestring nullable required
statusstring required
tierstring required
profilestring required
price_centsinteger required
billedboolean required
includedboolean 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.

included_in_trialboolean required

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

trial_tierstring nullable required

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

complimentaryboolean

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.

charged_centsinteger nullable 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.

sources_fetchedinteger nullable required

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

notes_writteninteger nullable required
step_idstring nullable required

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

step_namestring nullable required

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

step_detailstring nullable

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.

chapters_totalinteger nullable

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.

report_wordsinteger nullable required

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

blocked_onstring nullable 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.

blocked_codestring nullable

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.

wait_reason'provider_billing' | 'provider_rate_limit' | 'provider_outage' | 'platform_capacity' | 'platform_transient' | 'vault_unavailable' | 'null' nullable

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.

failure_reasonstring nullable 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.

aborted_bystring nullable 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.

failure_request_idstring nullable required
channelstring required
dry_runboolean 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.

created_atstring required
started_atstring nullable required
finished_atstring nullable required
duration_msinteger nullable 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).

version_ofstring nullable 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).

version_groupstring

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

notes_retaggedinteger required

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

Changes

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