Documentation Index
Fetch the complete documentation index at: https://staplehire.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Use jobs poll after async commands like sourcing start and candidates enrich before reading generated results.
JOB_ID=$(staplehire candidates enrich <candidateId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID" --interval 2000 --timeout 120000
Quickstart
JOB_ID=$(staplehire sourcing start <roleId> | jq -r '.job.id')
staplehire jobs poll "$JOB_ID"
staplehire sourcing prospects <roleId>
{
"job": {
"id": "job_...",
"type": "source_role_prospects",
"status": "done",
"role_id": "550e8400-e29b-41d4-a716-446655440000",
"result": {}
}
}
Parameters
| Flag | Required | Description |
|---|
<jobId> | Yes | Job ID returned by an async command |
--interval <ms> | No | Poll interval in milliseconds |
--timeout <ms> | No | Maximum wait time before exit code 9 |
Job statuses
| Status | Meaning |
|---|
pending | Job is queued |
claimed | Worker is processing the job |
done | Job completed successfully |
failed | Job failed |
Exit codes
| Code | Meaning |
|---|
0 | Job reached done |
1 | Job reached failed |
9 | Poll timed out; job may still be running |
Examples
Poll with a longer timeout
staplehire jobs poll <jobId> --interval 5000 --timeout 300000
Inspect a job without blocking
staplehire jobs get <jobId>
List recent sourcing jobs for a role
staplehire jobs list --role-id <roleId> --type source_role_prospects --include-history
Common errors
| Error | Cause | Fix |
|---|
Exit code 9 | Timeout elapsed | Re-run jobs poll, increase --timeout, or inspect with jobs get |
NotFoundError | Job ID is wrong | Use the job.id returned by the async command |
failed status | Worker failed the job | Read the job result and retry the source command if appropriate |
FAQ
Does timeout cancel the job?
No. Exit code 9 means the CLI stopped waiting. The job may still finish later.
Which commands create jobs?
candidates enrich, sourcing start, and some interview design generation flows create async jobs.
Should agents always poll?
Yes. Agents should poll after async commands before reading results.
Related: Source candidates with the Staplehire CLI · Enrich a candidate with the Staplehire CLI · CLI errors