Synchronous results

POST /v1/runs is asynchronous by default — it starts the run and returns immediately. To wait for the result in the same request, send an RFC 7240 Prefer: wait header.

Prefer: wait

curl https://api.nicia.ai/v1/runs \
  -H "x-api-key: $NICIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=120" \
  -d '{ "agentId": "…", "input": { … } }'

• wait=<seconds> blocks until the run reaches a terminal state.
• A bare wait uses the default of 60 seconds.
• The maximum is 120 seconds (wait=600 is clamped to 120); wait=0 means don’t wait. For longer work, poll or stream instead.

Reading the result

The response is always a run object. Check state:

state	Meaning
closed	Finished successfully — read output.
failed	Errored — read failureReason / failureCategory.
abandoned	Cancelled.
active	Still running — the deadline passed before it finished.

{
  "data": {
    "run": {
      "id": "0c7f1e9a-2b4d-4f3a-9c1e-8a2d6f4b0c7f",
      "state": "closed",
      "output": { "summary": "Report summarized in three bullet points." }
    }
  }
}

Graceful degradation

If the run doesn’t finish before your deadline, you don’t lose it — the response comes back with state: "active" and the same run id. Continue asynchronously: poll GET /v1/runs/{id}, stream it, or let a completion webhook notify you. A dropped connection never cancels the run.

This makes Prefer: wait safe for both quick agents (you get the answer inline) and long-running ones (you fall through to async automatically).