Check Job Status

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",
  "created_at": "2025-12-28T14:00:00Z",
  "updated_at": "2025-12-28T14:05:00Z"
}

GET

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",
  "created_at": "2025-12-28T14:00:00Z",
  "updated_at": "2025-12-28T14:05:00Z"
}

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

When the job was created

string

When the job was last updated

object

Email-specific tracking data (for email jobs only)

Show properties

string

Sender email address

string

Recipient email address

string

Email subject

string

Email delivery status

number

Number of times the email was opened

number

Number of link 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
  },
  "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",
  "created_at": "2025-12-28T14:00:00Z",
  "updated_at": "2025-12-28T14:05:00Z"
}

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.

`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)
`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, poll this endpoint to get results

Tag Value Create Goal

Overview

Email

Email Inbox

Voice

SMS

Commerce

Enrichment

Verification

Research

Build

Notifications

Receipts & Analytics

Other

Compute

Browser

Check Job Status

Authentication

Path Parameters

Response

Error codes

Notes

​Authentication

​Path Parameters

​Response

​Error codes

​Notes

Authentication

Path Parameters

Response

Error codes

Notes