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

# POST /v1/self-improve/runs

> Start a Self-Improve run.

Starts a loop that changes the agent prompt, pushes it to the provider, and runs the simulation to score it. At the end, Bluejay saves the best prompt as one new `latest` version. The previous version stays. The `production` label does not move.## Confirm the run1) Send the request without `confirmed`. The response has `needs_confirmation: true` and a `preview` text. Nothing runs.
2) Send the same request with `confirmed: true`. The response has `run_id`.## Limits- The agent must be a Vapi, ElevenLabs, or Retell agent with a provider ID. Other agents return 400.
- `max_iterations` is 5 by default and 20 at most.
- `metric_count` is 5 by default and 20 at most.
- One agent can have one active run. A second run returns 409.Rate limit: 30 requests per minute.## Headers

\<table><thead><tr><th>Name</th>
            \<th>Type</th>
            \<th>Required</th>
            \<th>Description</th></tr></thead>
        \<tbody /></table>

## Request body

\<table><thead><tr><th>Name</th>
            \<th>Type</th>
            \<th>Required</th>
            \<th>Description</th></tr></thead>
        \<tbody /></table>

## ResponseA `200` response has no body.## Status codes| Status | Meaning |
| - | - |
| `200` | Successful Response |
| `422` | Validation Error |## Example request```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl --request POST \
  --url https://api.getbluejay.ai/v1/self-improve/runs \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": 123,
    "simulation_id": 123,
    "target_pass_rate": 0.9,
    "max_iterations": 5,
    "min_improvement": 0.02,
    "metric_count": 5,
    "success_metric_ids": [
      "<string>"
    ],
    "confirmed": false
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.