> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Job Status

> Check the status of an async job using its request ID

## Authentication

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

## Path Parameters

<ParamField path="id" type="string" required>
  The request ID returned from a tool invocation (e.g., `req_xyz789`)
</ParamField>

## Response

<ResponseField name="request_id" type="string">
  The job's unique identifier
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: `pending`, `processing`, `completed`, or `failed`
</ResponseField>

<ResponseField name="tool" type="string">
  The tool that was invoked (e.g., `email`, `research`)
</ResponseField>

<ResponseField name="result" type="object">
  Job result data (present when status is `completed`)
</ResponseField>

<ResponseField name="error" type="string">
  Human-readable error message (present when status is `failed`). Includes a
  `(ref: <id>)` correlation id for support.
</ResponseField>

<ResponseField name="error_code" type="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](#error-codes).
</ResponseField>

<ResponseField name="created_at" type="string">
  When the job was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the job was last updated
</ResponseField>

<ResponseField name="email_tracking" type="object">
  Email-specific tracking data (for email jobs only)

  <Expandable title="properties">
    <ResponseField name="from" type="string">
      Sender email address
    </ResponseField>

    <ResponseField name="to" type="string">
      Recipient email address
    </ResponseField>

    <ResponseField name="subject" type="string">
      Email subject
    </ResponseField>

    <ResponseField name="status" type="string">
      Email delivery status
    </ResponseField>

    <ResponseField name="opens" type="number">
      Number of times the email was opened
    </ResponseField>

    <ResponseField name="clicks" type="number">
      Number of link clicks
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://win.oneshotagent.com/v1/requests/req_xyz789 \
    -H "X-Agent-ID: 0x1234...5678"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</RequestExample>

<ResponseExample>
  ```json Pending theme={null}
  {
    "request_id": "req_xyz789",
    "status": "pending",
    "tool": "email",
    "created_at": "2025-12-28T14:00:00Z",
    "updated_at": "2025-12-28T14:00:00Z"
  }
  ```

  ```json Completed theme={null}
  {
    "request_id": "req_xyz789",
    "status": "completed",
    "tool": "email",
    "result": {
      "success": true,
      "message_id": "msg_abc123"
    },
    "email_tracking": {
      "from": "agent@oneshotagent.com",
      "to": "user@example.com",
      "subject": "Hello",
      "status": "delivered",
      "opens": 1,
      "clicks": 0
    },
    "created_at": "2025-12-28T14:00:00Z",
    "updated_at": "2025-12-28T14:02:30Z"
  }
  ```

  ```json Failed theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## 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