The run

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

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.

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.

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.