> ## Documentation Index
> Fetch the complete documentation index at: https://jesse-7a8b4a1d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# The run

> What GET /v1/searches/{id} returns, and the five states a run can end in.

```bash theme={null}
curl -s -H "Authorization: Bearer $ENIAC_CREDENTIAL" \
  "https://eniac.floworks.ai/v1/searches/6f1c0c5b9a1e4b7b8d2f3a4c5e6d7f80"
```

| Field | Type | Meaning |
| - | - | - |
| `id` | string | The run id, 32 lowercase hexadecimal characters. |
| `status` | string | `running`, or one of the five terminal states below. |
| `source` | string | `api` when the run was started with an API key, `playground` when it was started with a session token. |
| `query` | string | The query as the server stored it. |
| `target` | integer | The target you asked for. |
| `speed` | string | `fast` or `advanced`, after the server's own reading of what you sent. |
| `relax` | boolean | Whether filter relaxation is on for this run. |
| `sites` | string\[] | The domains this run is restricted to, expanded and de-duplicated. Empty means the open web. |
| `siteFocus` | string | The page-type phrase, when `sites` named page types rather than domains. Empty otherwise. |
| `where` | string | The last stage the run reached, such as `round 2, filter 1 (…)`. This is the field that tells you how far an interrupted run got. |
| `stopRequested` | boolean | `true` once a stop has been asked for, by you or by the deadline. |
| `stopReason` | string | `stop` when you called stop, `deadline` when the run ran out of wall-clock time, `null` otherwise. |
| `billableAccruedMicrousd` | integer | What the run has spent so far, in micro-USD, on the scale you are charged. |
| `billableInFlightMicrousd` | integer | What is committed to calls that have not come back yet, same scale. |
| `reservationMicrousd` | integer | What was reserved when the run was created: always 5000000, one \$5.00 hold. A long run's hold grows beyond this on the wallet, but this field records the opening amount and is never updated, so do not read it as the current hold. |
| `usd` | string | `billableAccruedMicrousd` as a six-decimal dollar string, for clients that must not use binary floats. |
| `usdDisplay` | string | The same figure formatted for a user, such as `$1.23`. |
| `lastSeq` | integer | The highest event sequence number written for this run. It is also a valid cursor to resume the stream from. |
| `createdAt` | string | ISO 8601 timestamp. |
| `updatedAt` | string | ISO 8601 timestamp. |
| `finishedAt` | string | ISO 8601 timestamp, or `null` while the run is going. |
| `deadlineAt` | string | ISO 8601 timestamp. A run still going at this point is ended by the server. |
| `lastHeartbeatAt` | string | ISO 8601 timestamp, or `null` before the run's first checkpoint. |
| `result` | object | The `final` event once the run is terminal, or `null`. Only on the single-run read, never in the list. |

Both reads answer `Cache-Control: no-store`. The `*Microusd` fields are integers in micro-USD, so 1000000 is one dollar; `usd` and `usdDisplay` are strings. No money figure in this API is a float.

## The five terminal states

`status` is `running` until the run lands, and then it is exactly one of these and never changes again. A polling loop should treat any status other than `running` as the end.

| Status | Meaning |
| - | - |
| `done` | The run finished its rounds and produced a result. `result.met` says whether it reached your `target`. |
| `stopped` | The run was asked to stop and unwound early. Normally that is because you called stop. |
| `budget_exhausted` | The run hit a spend ceiling and was ended deliberately, either because it reached the per-run cap or because your balance ran out mid-run. You are charged for what it actually spent, and you keep whatever rows had already been verified. |
| `interrupted` | The service ended the run rather than the search ending itself: the process it was running in went away, or the run passed `deadlineAt`. On a restart this is expected rather than exceptional. `stopReason: "deadline"` distinguishes a timeout from a lost process, and `where` says how far it got. |
| `error` | The run failed. The reason is an `error` event in the stream, not a field on the run. A `402` refusal also leaves a run in this state with no events at all. |

<Warning>
  **A terminal run is not necessarily an empty one, and `done` is not the only success.** `stopped` and `budget_exhausted` both carry a `result` with the rows that passed the full funnel before the run ended, usually with `result.met` false. Treating anything other than `done` as a failure throws away rows you have already paid for.

  The reverse also holds: `result` can be `null` on a terminal run. An `interrupted` run that died before writing its tail has no `final` event to return, and neither does the `error` row left behind by a `402`. Check the field rather than the status.
</Warning>

## Reading a stopped or exhausted run

The `final` event in `result` carries `stopped: true` and `stopped_at` whatever the early ending was: your stop, the spend ceiling, the balance running out, the deadline, or a lost process. So `result.stopped` tells you the table is partial, and `status` tells you why it is partial. One without the other is not enough.

## Cost on the run

`billableAccruedMicrousd` is on the same scale as the `usd` on a `cost` event: what you are charged, with nothing in it that the `cost` events do not also report. The amount actually captured when the run settles is `billableAccruedMicrousd + billableInFlightMicrousd` as of the moment it ended, capped at the hold, so a run that was mid-call when it stopped is charged for that call.

The hold itself is not a field on the run. It is released down to the captured amount when the run settles, and the settlement lands before `status` becomes terminal, so a terminal run is never still holding money. See [Cost](/cost).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.