---
title: "Generate an AI analysis of performance bottlenecks"
method: POST
path: "/simulations/{simulationId}/analyze-bottlenecks"
tags: ["Understand"]
---

# Generate an AI analysis of performance bottlenecks

`POST /simulations/{simulationId}/analyze-bottlenecks`

## Request

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

Uses GPT-5 to identify performance bottlenecks in the simulation based on
the current resource configuration, metric history, and event log.
Returns a detailed analysis and, where applicable, a DigitalOcean-specific
migration recommendation.

Set `beginnerMode: true` for simplified language.

**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
  - `beginnerMode` boolean: Return simplified analysis

## Response `200`

Bottleneck analysis

- object
  - `analysis` string: Detailed bottleneck analysis
  - `doRecommendation` object, nullable: DigitalOcean-specific migration/right-sizing recommendation (if applicable)
    - `suggestedDropletSize` string, required: Recommended Droplet size slug (e.g. "s-2vcpu-4gb")
    - `estimatedHourlyRate` number, required: Hourly rate for the suggested Droplet size in USD
    - `estimatedMonthlyCost` number, required: Estimated monthly cost for all Droplets in USD
    - `currentHourlyCost` number, required: Current compute-tier hourly cost (compute resources only — see savingsBasis)
    - `estimatedHourlySavings` number, required: Estimated hourly savings vs current compute-tier cost
    - `estimatedMonthlySavings` number, required: Estimated monthly savings in USD
    - `savingsPercent` number, required: Savings as a percentage of the compute-tier baseline (0–70)
    - `savingsIsComputed` boolean, required: True when savings are derived from real cost data rather than a default estimate
    - `savingsBasis` 'compute-only', required: Indicates that savings are computed against compute-tier costs only; non-compute resources (managed DB, cache, load balancer) are excluded from the baseline
    - `reason` 'right-sizing' | 'migration' | 'scale-out', required: The primary recommendation category
    - `numDroplets` number, required: Suggested number of Droplets
    - `reversibilityTier` 'instant' | 'minutes' | 'hours' | 'days', required: How hard this recommendation is to reverse — cross-provider migrations classify as "days"
    - `reversibilityReason` string, required: Human-readable explanation of the dominant reversibility factor
    - `estimatedMinutesMin` number, required: Lower bound of estimated rollback time in minutes
    - `estimatedMinutesMax` number, required: Upper bound of estimated rollback time in minutes
    - `basis` 'rule_based', required: Always "rule_based" — reversibility is classified deterministically, not via LLM

## Other responses

- `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)