---
title: "Run the AI agent asynchronously"
method: POST
path: "/public/agent/run/async"
tags: ["Agent"]
---

# Run the AI agent asynchronously

`POST /public/agent/run/async`

## Request

- Base URL: `https://api.johnsessentials.com/api/v1`
- URL: `https://api.johnsessentials.com/api/v1/public/agent/run/async`
- Auth: HTTP bearer

Same request body and paid gates as `/public/agent/run`, but returns
`{job_id, session_id, conversation_id, status}` immediately instead of
blocking. Consume live progress at
`/public/agent/jobs/{jobId}/stream`; cancel via
`DELETE /public/agent/jobs/{jobId}`. Cost is debited against the API
key's monthly ledger when the run finishes (same amounts as the sync
route).

## Headers

- `Idempotency-Key` string

## Request body

- AgentRunRequest
  - `conversation_id` string, uuid: Resume a saved conversation thread (see /public/agent/conversations). Omit to start a new one — the response returns its id.
  - `file_ids` string[]: File IDs to attach (from POST /public/files)
  - `message` string, required: The task/prompt for the agent to run

## Response `200`

Run accepted and started; stream for progress.

- Envelope
  - `data` unknown
  - `error` ErrorBody: Additional fields per code (validation errors, retry_after, hints) appear at this level. additionalProperties: true is intentional.
    - `code` 'auth_missing_header' | 'auth_malformed_header' | 'auth_invalid_key' | 'auth_expired_key' | 'auth_inactive_key' | 'auth_scope_missing' | 'quota_calls_exceeded' | 'quota_cost_exceeded' | 'quota_storage_exceeded' | 'quota_agent_runs_exceeded' | 'credit_exhausted' | 'tool_not_found' | 'tool_input_invalid' | 'tool_file_too_large' | 'tool_file_not_found' | 'tool_unsupported' | 'tool_timeout' | 'tool_internal' | 'idempotency_key_in_use' | 'agent_max_iterations' | 'agent_unauthorized_tool' | 'agent_invalid_plan' | 'workflow_not_found' | 'workflow_invalid' | 'bad_request' | 'forbidden' | 'not_found' | 'conflict' | 'internal_error' | 'service_unavailable', required: Stable canonical code from the taxonomy. Branch on this, not on `message`. Full list at /api/errors.
    - `doc_url` string, uri, required
    - `message` string, required
    - `request_id` string, uuid
  - `meta` EnvelopeMeta, required
    - `rate_limit` object
      - `limit` integer
      - `remaining` integer
      - `reset` integer: Unix seconds
    - `timestamp` string, date-time, required
    - `version` string, required
  - `request_id` string, uuid, required
  - `success` boolean, required

## Other responses

- `400`: Request validation failed.
- `401`: Auth failed (missing/malformed/invalid/expired/inactive key).
- `402`: Monthly USD cost cap reached for this key (quota_cost_exceeded). Phase 3 / M3.
- `403`: API key lacks required scope (auth_scope_missing).
- `404`: conversation_id not found or not owned by this account.
- `409`: Idempotency-Key collision — same key with a different body, or a concurrent in-flight request with the same key.
- `429`: Sliding 1-hour rate limit exceeded.
- `500`: Server error. NOT cached by Idempotency-Key — safe to retry.

---

[API](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api.md) · [All operations](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api/llms.txt) · [OpenAPI document](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api/revisions/56586ff78e6d?raw)