Skip to main content
GET

Authentication

Requires X-Agent-ID header with your wallet address. You must be the owner of the job to access its status.

Path Parameters

string
required
The request ID returned from a tool invocation (e.g., req_xyz789)

Response

string
The job’s unique identifier
string
Current job status: pending, processing, completed, or failed
string
The tool that was invoked (e.g., email, research)
object
Job result data (present when status is completed)
string
Human-readable error message (present when status is failed). Includes a (ref: <id>) correlation id for support.
string
Stable, machine-readable error code (present when status is failed). Branch on this to decide how to react — some failures are actionable (fund wallet, fix input) and some are safe to retry. See Error codes.
string
Error category (present when status is failed). E.g., bad_request, upstream_rejected, payment_required.
number
HTTP-like status code mapped to the error (present when status is failed).
string
When the job was created
string
When the job was last updated
object
Email-specific tracking data (for email jobs only)

How results are delivered

Paid tools return 202 with a request_id as soon as the job is queued; the work runs on a worker and the result lands on this endpoint. The SDKs wait for it two ways at once and take whichever answers first:
  • WebSocket push — the SDK subscribes to /v1/requests/subscribe for the request id. The worker publishes processing when it picks the job up and the terminal completed / failed message with the result the moment it writes it. If the job already finished by the time the subscription lands, the server sends a snapshot immediately.
  • HTTP polling — in parallel, the SDK polls this endpoint on a short backoff (300ms → 600ms → 1s → 2s), relaxing to 5s once the push channel has proven itself for this request. Polling is the source of truth; push is an accelerator, so a dropped socket never delays a result.
Typical wall-clock from dispatch to result is a few seconds for enrichment, verification and web reads, and minutes for research and builds. If you call the API without an SDK, poll this endpoint with a sub-second first check and back off; there is no completion webhook. Calls made with wait: false can be resolved later with the SDK’s waitForResult(requestId).

Error codes

When status is failed, error_code is one of the stable values below. The human-readable error string may change; error_code is the contract to branch on.

Notes

  • Jobs are retained for 30 days
  • You can only access jobs you own (verified by wallet address)
  • For async tools like email and research, the SDK waits on this endpoint for you — see How results are delivered