> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inboxfound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs and polling

> Every lookup is a job. Submit, poll, read.

Submitting returns a job immediately. The result arrives when the checks finish, and the job is stored on your account so a dropped connection never loses an outcome.

## Lifecycle

```mermaid theme={null}
flowchart LR
  A[POST /verify or /find] -->|202| B[queued]
  B --> C[running]
  C --> D[complete]
  C --> E[incomplete]
  C -.-> F[review]
```

| `execution_state` | Meaning | Terminal |
| - | - | - |
| `queued` | Admitted, waiting for capacity. | no |
| `running` | Checks in progress. | no |
| `complete` | Every stage reached a final state. `result` is set. | yes |
| `incomplete` | A stage did not finish. `result` may be missing or partial and is never presented as a confident negative. | yes |
| `review` | Parked for an operator. Its reservation is being reconciled; do not resubmit it. | no |

> [!NOTE]
>
> `execution_state` says whether the work finished. `billing` says what happened to the money. Neither implies the other: a `complete` job can be `released` (no definite answer), and a `reserved` job can still be `running`.

## Polling

Read `GET /api/v1/jobs/{id}` every few seconds. Reading is free, never changes the job, and the same job can be read by any key on the account with the matching scope.

## Idempotency

Every submission requires an `Idempotency-Key` header. Retrying with the same key **and the same input** returns the original job; nothing is started or charged twice. Input is canonicalised before comparison, so a differently ordered but equivalent body is the same request. The same key with a different input returns `409 idempotency_conflict`.

## Job envelope

| Field | Type | Meaning |
| - | - | - |
| `id` | uuid | Stable for the life of your account. |
| `operation` | `find` \| `verify` | Which operation ran. |
| `execution_state` | enum | See above. |
| `billing` | `reserved` \| `charged` \| `released` | State of the reservation. |
| `charged_micros` | integer | Micro-dollars captured. `0` until `billing` is `charged`. |
| `rate_micros` | integer | The rate reserved at submission. A later price change never re-prices a job. |
| `result` | object \| null | See [Results](https://docs.inboxfound.com/results.md). Null until the engine has answered. |


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