---
title: "Answer a run’s clarification questions"
method: POST
path: "/v1/runs/{id}/clarify"
tags: ["runs"]
---

# Answer a run’s clarification questions

`POST /v1/runs/{id}/clarify`

## Request

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

Answers the questions a `clarifying` run is waiting on, and admits it: the reservation, the trial allowance and the Workflow launch all happen now, against the account as it stands now. Answer by `axis`, not by position. An answer of `you_decide` (or an empty string) records that question’s stated assumption as the decision, and `skip: true` does that for every question at once — which is also what the 30-minute time-box does if nobody comes back. Answering a run that is no longer `clarifying` is a 409, except when it was admitted a moment ago by a racing click or by the time-box, which answers 202 with the run that won.

## Path parameters

- `id` string, required

## Request body

- ClarifyRunBody
  - `answers` object[]
    - `axis` string, required
    - `answer` string, required: A few words. The literal `you_decide` (or an empty string) records the stated assumption as the decision instead.
  - `skip` boolean: Proceed on every stated assumption without answering. The same thing the 30-minute time-box does.

## Response `202`

Run queued

- RunCreated
  - `id` string, 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.
  - `tier` 'auto' | 'light' | 'brief' | 'full' | 'premier' | 'dissertation', required
  - `price_cents` integer, nullable, required
  - `events_url` string, required
  - `created_at` string, required
  - `clarification` Clarification
    - `status` 'asking' | 'answered' | 'assumed', required
    - `round` integer, required
    - `score` integer
    - `questions` ClarificationQuestion[], required
      - `axis` string, required: The named dimension this question is about (`scope`, `time_window`, `geography`, …). Answer by axis, not by position.
      - `question` string, required
      - `assumption` string, required: What the run will do if this question is not answered. Shown behind "You decide" and in the skip-all confirmation, and printed in the report’s Assumptions paragraph.
      - `evidence` string, nullable, required: The span of the customer’s own question that prompted this one, when it could be quoted verbatim.
      - `suggested_answers` string[], required
    - `answers` ClarificationAnswer[], required
      - `axis` string, required
      - `question` string
      - `answer` string, required: The literal `you_decide` when the customer left this to us; the assumption then records the decision.
      - `you_decide` boolean
      - `answered_at` string
    - `assumptions` string[], required: Every default this run is proceeding on — verbatim the sentences its report prints.
    - `expires_at` string, nullable, required: When an unanswered interview times out; what happens then is `on_timeout`. Null once the interview is settled.
    - `on_timeout` 'start' | 'close': Present while `status` is `asking`: what happens at `expires_at` if nobody answers. `start` admits the run on its stated assumptions (or closes it without charge if it cannot be admitted then — spend cap, no payment method); `close` ends it without starting and without charge, which is what an interview that found nothing to research does.
    - `resolution` 'answered' | 'skipped' | 'timeout' | 'auto' | 'off' | 'unassessed' | 'null', nullable, required
    - `note` string: A sentence about the interview rather than about the question: that the ambiguity assessment could not be made (`resolution: "unassessed"`), that nothing has started while we ask what to research, or that the time-box closed the run without charge.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `402`: Spend cap exceeded, or no allowance left
- `403`: Insufficient scope or plan
- `404`: Not found
- `409`: This run is not waiting on clarification
- `429`: Rate limited or over quota
- `500`: Internal error

---

[API](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api.md) · [All operations](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/revisions/726ef831ebf4?raw)