Run Statuses and Termination Reasons
FindAll runs progress fromqueued → running → terminal state (completed, failed, or cancelled).
A run is considered active when it has status queued, running and has active candidate generation, evaluation, and enrichments ongoing.
Status Definitions
| Status | Description | Can Extend? | Can Enrich? |
|---|---|---|---|
queued | Run is waiting to start processing | N/A | N/A |
running | Run is actively evaluating candidates | ❌ No | ✅ Yes |
completed | Run finished (see termination reasons below) | Depends* | ✅ Yes |
failed | Run encountered an error | ❌ No | ❌ No |
cancelled | Run was cancelled by user | ❌ No | ❌ No |
Termination Reasons
When a run reaches a terminal state, it will have one of these termination reasons:| Termination Reason | Description | Can Extend? |
|---|---|---|
match_limit_met | Successfully found the requested number of matches | ✅ Yes |
low_match_rate | Match rate too low to continue efficiently | ❌ No - try a more powerful generator |
candidates_exhausted | All available candidates have been processed | ❌ No - broaden query |
error_occurred | Run encountered an error and cannot be continued | ❌ No |
timeout | Run timed out and cannot be continued | ❌ No |
user_cancelled | Run was cancelled by the user | ❌ No |
Related Topics
- Generators and Pricing: Understand generator options and pricing
- Preview: Test queries with ~10 candidates before running full searches
- Enrichments: Extract additional structured data for matched candidates
- Extend Runs: Increase match limits without paying new fixed costs
- Streaming Events: Receive real-time updates via Server-Sent Events
- Webhooks: Configure HTTP callbacks for run completion and matches
- API Reference: Complete endpoint documentation