---
title: "Submit async AI analysis job"
method: POST
path: "/ai-jobs"
tags: ["AI Jobs"]
---

# Submit async AI analysis job

`POST /ai-jobs`

## Request

- Base URL: `https://www.cloudworldmodel.ai/api`
- URL: `https://www.cloudworldmodel.ai/api/ai-jobs`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-PAYMENT`
  - API key in header `PAYMENT-SIGNATURE`

Creates an async AI analysis job for a simulation. Immediately returns a
`jobId` (HTTP 202) so callers are never blocked by the ~11 s gateway
timeout. Supported job types:

- `explain` — natural-language explanation of simulation behaviour
- `troubleshoot` — diagnosis and remediation steps for a described issue
- `analyze_bottlenecks` — ranked bottleneck detection with remediation
- `optimize` — infrastructure optimisation suggestions

**Poll flow:**
1. `POST /api/ai-jobs` → receive `jobId`
2. `GET /api/ai-jobs/{jobId}` → poll until `status` is `completed`
3. `GET /api/ai-jobs/{jobId}/results` → retrieve the AI output

**Authentication:** Required. Provide `Authorization: Bearer cwm_live_…`
or an x402 payment header with call type `ai_analysis`.

## Request body

- object
  - `simulationId` string, required: ID of the simulation to analyze
  - `type` 'explain' | 'troubleshoot' | 'analyze_bottlenecks' | 'optimize', required: Type of AI analysis to run
  - `beginnerMode` boolean: Return simplified, jargon-free output
  - `issue` string: Required for troubleshoot — describe the problem

## Response `202`

AI job accepted

- object
  - `jobId` string: AI job ID — use with /ai-jobs/{jobId} and /ai-jobs/{jobId}/results
  - `status` 'pending'
  - `createdAt` string, date-time
  - `message` string

## Other responses

- `400`: Invalid request data — structured field-level error
- `401`: Authentication required or invalid API key
- `402`: Payment required — the endpoint is metered and no API key was provided. The response body follows the [x402 v2 protocol](https://x402.org) and describes one or more USDC payment options that the caller can select before retrying the request. Base is always the first option and uses `X-PAYMENT`. When an `accepts` entry for Solana is present, it is an additional USDC-SPL option that uses `PAYMENT-SIGNATURE` and its `extra.feePayer` value. The server verifies either payment through the PayAI facilitator at `https://facilitator.payai.network`. The `PAYMENT-REQUIRED` response header carries this entire JSON body as a base64-encoded string for protocol-aware clients. Call `GET /api/billing/x402/config` to retrieve the current price table and wallet address and `paymentOptions` before constructing a payment.
- `404`: Resource not found
- `500`: Internal server error

---

[API](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api.md) · [All operations](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api/revisions/ecc3ad1ff07f?raw)