curl -X GET https://win.oneshotagent.com/v1/requests/req_xyz789 \
-H "X-Agent-ID: 0x1234...5678"
const response = await fetch(
"https://win.oneshotagent.com/v1/requests/req_xyz789",
{
headers: {
"X-Agent-ID": "0x1234...5678",
},
},
);
const job = await response.json();
console.log(job.status);
{
"request_id": "req_xyz789",
"status": "pending",
"tool": "email",
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:00:00Z"
}
{
"request_id": "req_xyz789",
"status": "completed",
"tool": "email",
"result": {
"success": true,
"message_id": "msg_abc123"
},
"email_tracking": {
"from": "[email protected]",
"to": "[email protected]",
"subject": "Hello",
"status": "delivered",
"opens": 1,
"clicks": 0
},
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:02:30Z"
}
{
"request_id": "req_xyz789",
"status": "failed",
"tool": "email",
"error": "Insufficient funds to complete this paid action. Fund your wallet and retry. (ref: a1b2c3d4)",
"error_code": "insufficient_funds",
"error_category": "payment_required",
"error_status": 402,
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:05:00Z"
}
Other
Check Job Status
Check the status of an async job using its request ID
GET
/
v1
/
requests
/
{id}
curl -X GET https://win.oneshotagent.com/v1/requests/req_xyz789 \
-H "X-Agent-ID: 0x1234...5678"
const response = await fetch(
"https://win.oneshotagent.com/v1/requests/req_xyz789",
{
headers: {
"X-Agent-ID": "0x1234...5678",
},
},
);
const job = await response.json();
console.log(job.status);
{
"request_id": "req_xyz789",
"status": "pending",
"tool": "email",
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:00:00Z"
}
{
"request_id": "req_xyz789",
"status": "completed",
"tool": "email",
"result": {
"success": true,
"message_id": "msg_abc123"
},
"email_tracking": {
"from": "[email protected]",
"to": "[email protected]",
"subject": "Hello",
"status": "delivered",
"opens": 1,
"clicks": 0
},
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:02:30Z"
}
{
"request_id": "req_xyz789",
"status": "failed",
"tool": "email",
"error": "Insufficient funds to complete this paid action. Fund your wallet and retry. (ref: a1b2c3d4)",
"error_code": "insufficient_funds",
"error_category": "payment_required",
"error_status": 402,
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:05:00Z"
}
Authentication
RequiresX-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 failedstring
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
curl -X GET https://win.oneshotagent.com/v1/requests/req_xyz789 \
-H "X-Agent-ID: 0x1234...5678"
const response = await fetch(
"https://win.oneshotagent.com/v1/requests/req_xyz789",
{
headers: {
"X-Agent-ID": "0x1234...5678",
},
},
);
const job = await response.json();
console.log(job.status);
{
"request_id": "req_xyz789",
"status": "pending",
"tool": "email",
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:00:00Z"
}
{
"request_id": "req_xyz789",
"status": "completed",
"tool": "email",
"result": {
"success": true,
"message_id": "msg_abc123"
},
"email_tracking": {
"from": "[email protected]",
"to": "[email protected]",
"subject": "Hello",
"status": "delivered",
"opens": 1,
"clicks": 0
},
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:02:30Z"
}
{
"request_id": "req_xyz789",
"status": "failed",
"tool": "email",
"error": "Insufficient funds to complete this paid action. Fund your wallet and retry. (ref: a1b2c3d4)",
"error_code": "insufficient_funds",
"error_category": "payment_required",
"error_status": 402,
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:05:00Z"
}
How results are delivered
Paid tools return202 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/subscribefor the request id. The worker publishesprocessingwhen it picks the job up and the terminalcompleted/failedmessage 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.
wait: false can be
resolved later with the SDK’s waitForResult(requestId).
Error codes
Whenstatus 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.
error_code | Meaning | What to do |
|---|---|---|
insufficient_funds | Wallet/credit balance too low to settle the charge | Fund the wallet — do not blind-retry |
payment_failed | Payment couldn’t be settled on-chain (not a balance shortfall) | Check the wallet, then retry |
invalid_input | Validation failed / bad parameters / unknown tool | Fix the request — retrying as-is won’t help |
content_blocked | Blocked by content safety / moderation | Adjust the content and retry |
rate_limited | An upstream provider rate-limited the request | Retry after a brief wait |
provider_unavailable | An upstream provider timed out or was unavailable | Safe to retry |
provider_auth | An upstream provider rejected our credentials | Retry; contact support if it persists |
enrichment_exhausted | No data found for the person (all providers exhausted) | Provide more identifiers (email, LinkedIn URL, full name + company) |
target_unreachable | The hostname in the requested URL could not be resolved | Check the domain is spelled correctly and publicly reachable — retrying as-is won’t help |
source_unsupported | The requested site cannot be read | Use a different URL or source — retrying as-is won’t help |
checkout_failed | Commerce checkout could not be completed | Verify the cart/quote and retry |
internal_error | Unclassified internal failure | Safe to retry; contact support with the ref if it persists |
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