---
title: "Generate AI troubleshooting guidance for a simulation issue"
method: POST
path: "/simulations/{simulationId}/troubleshoot"
tags: ["Understand"]
---

# Generate AI troubleshooting guidance for a simulation issue

`POST /simulations/{simulationId}/troubleshoot`

## Request

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

Accepts a plain-text description of a problem (e.g. "latency spikes every
30 seconds") and uses GPT-5 to analyse the simulation's current state and
event history to produce step-by-step troubleshooting guidance.

**Authentication:** Requires an API key (`write` scope) or an x402
micro-payment (3 credits — $0.0030 USDC on Base). Pass
`Authorization: Bearer <key>` for API key access, or include a signed
x402 payment header (no account required). Use
`GET /api/billing/x402/config` to discover the live price.

## Path parameters

- `simulationId` string, required

## Request body

- object
  - `issue` string, required: Plain-text description of the problem to investigate

## Response `200`

Troubleshooting guidance

- object
  - `guidance` string: Step-by-step troubleshooting guidance

## Other responses

- `400`: Missing issue description
- `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
- `429`: Rate limit exceeded
- `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)