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
},
"receipt_id": "rcpt_...",
"settlement_status": "settled",
"execution_status": "completed",
"effect_evidence": {
"vendor": "resend",
"ref": "<the provider's id for the sent email>",
"kind": "resend_email_id"
},
"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",
"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
},
"receipt_id": "rcpt_...",
"settlement_status": "settled",
"execution_status": "completed",
"effect_evidence": {
"vendor": "resend",
"ref": "<the provider's id for the sent email>",
"kind": "resend_email_id"
},
"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",
"error_status": 402,
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:05:00Z"
}
Where an async job stands; once finished, the result or a stable error code.
Jobs are retained for 30 days.
Authentication
Requires theX-Agent-ID header with your wallet address. You can only read jobs you own.
Path parameters
string
required
Request ID returned by a tool call (e.g.,
req_xyz789)Response
string
Job ID
string
pending, processing, completed, or failedstring
Tool called
object
Job result (when
completed)string
Message (when
failed), with a (ref: <id>) id for support.string
Stable code (when
failed). See Error codes.string
payment, validation, upstream, or internal (when failed).number
HTTP-like status code (when
failed).string
When the job was created
string
When the job was last updated
string
Whether the paid action ran:
pending, then completed or failed. With receipt_id; independent of settlement_status.object | null
The executing
vendor’s own ref for the action and its kind, or null when no vendor returned one.object
Email jobs only:
from, to, subject, status, opens, clicks.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
},
"receipt_id": "rcpt_...",
"settlement_status": "settled",
"execution_status": "completed",
"effect_evidence": {
"vendor": "resend",
"ref": "<the provider's id for the sent email>",
"kind": "resend_email_id"
},
"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",
"error_status": 402,
"created_at": "2025-12-28T14:00:00Z",
"updated_at": "2025-12-28T14:05:00Z"
}
How results are delivered
Most paid tools return202 with a request_id; the result appears here when the job finishes. A tool that answers in the same response returns 200; its own page says so. The SDKs wait for you. Without an SDK, poll with a sub-second first check and back off; there is no completion webhook. For wait: false, use the SDK’s waitForResult(requestId) later. Enrichment and web reads take seconds; research and builds take minutes.
Error codes
Whenstatus is failed, error_code is one of these stable values. The error string may change.
error_code | Meaning | What to do |
|---|---|---|
insufficient_funds | Balance too low to settle the charge | Fund the wallet. Do not blind-retry |
payment_failed | Payment could not be settled on-chain | Check the wallet, then retry |
invalid_input | Validation failed | Fix the request; do not retry as is |
content_blocked | Blocked by content safety | Adjust the content and retry |
rate_limited | The job was rate-limited | Retry after a brief wait |
service_unavailable | The tool timed out or was unavailable | Safe to retry |
service_auth | A fault on OneShot’s side | Retry; contact support if it persists |
enrichment_exhausted | No data found for the person | Provide more identifiers (email, LinkedIn URL, full name and company) |
target_unreachable | The hostname could not be resolved | Check the domain; do not retry as is |
source_unsupported | The site cannot be read | Use a different source; do not retry as is |
checkout_failed | Commerce checkout could not be completed | Verify the cart or quote and retry |
internal_error | A failure with no more specific code | Safe to retry; contact support if it persists |