# List an agent's proposed changes

Source: https://docs.vlayers.ai/reference/agents/list-agent-proposals

`GET /v1/agents/{id}/proposals` · scope `workspace:read`

The changes proposed for an agent's prompt, newest first: drafted by the improvement loop for a problem, or written by a person. Each carries its status, the replays before and after and the decision.

Requires an API key with the `workspace:read` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The agent id. Example: `"0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78"` |
| `status` | query | "drafted" \| "testing" \| "ready" \| "approved" \| "shipped" \| "rejected" \| "superseded" \| "refused" | no | Only proposals in this status. Example: `"ready"` |
| `problemId` | query | string | no | Only proposals for this problem. Example: `"0192f5fd-1625-7073-9c23-456789abcdef"` |
| `cursor` | query | string | no | The `nextCursor` of the previous page. Example: `"MjAyNi0xMS0xMg"` |
| `limit` | query | integer | no | How many items to return, 1–100. Default 25. Example: `20` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/agents/$AGENT_ID/proposals?status=ready" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { proposals } = await voicelayer.agents.listProposals('<agent-id>', { status: 'ready' });
console.log(proposals);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.agents.list_proposals("<agent-id>", status="ready")
print(result.proposals)
```

## Response `200`

```json
{
  "proposals": [
    {
      "id": "0192f5fe-2736-7184-8d34-56789abcdef0",
      "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",
      "baseVersionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012",
      "draftVersionId": "0192f5fb-f403-7e51-9a01-23456789abcd",
      "problemId": "0192f5fd-1625-7073-9c23-456789abcdef",
      "change": {
        "kind": "system_prompt",
        "text": "You are the booking assistant. When asked about availability, check it before answering."
      },
      "source": {
        "kind": "improvement",
        "ref": "0192f5fd-1625-7073-9c23-456789abcdef"
      },
      "reason": "Tells the agent to check availability before answering.",
      "evidence": {
        "before": [
          "0192f5fa-e3f2-7d40-8f90-0123456789ab"
        ],
        "after": [
          "0192f5f8-c1d0-7b2e-8d7e-8f9012345678"
        ],
        "distinctContacts": 9,
        "ownerCases": 5
      },
      "evidenceResult": {
        "problemCases": {
          "cases": 9,
          "passedBefore": 3,
          "passedAfter": 8
        },
        "regressions": 0,
        "refused": 0
      },
      "costEffect": {
        "beforeUsdPerSuccess": 0.12,
        "afterUsdPerSuccess": 0.1,
        "basis": "runs",
        "pricedFieldsChanged": []
      },
      "widening": {
        "capabilitiesAdded": [],
        "crossingsAdded": [],
        "widens": false
      },
      "approvers": {
        "userIds": null
      },
      "status": "ready",
      "decision": {
        "by": null,
        "door": null,
        "at": null,
        "refusalCode": null,
        "shippedVersionId": null
      },
      "autoShip": null,
      "draftDiverged": false,
      "quote": {
        "maxUsd": 1.4,
        "typicalUsd": 0.4
      },
      "spentUsd": 0.38,
      "createdBy": "user_2abc",
      "createdAt": "2026-10-20T15:04:05.000Z",
      "updatedAt": "2026-10-20T15:04:05.000Z",
      "expiresAt": "2026-10-20T15:04:05.000Z"
    }
  ],
  "nextCursor": null
}
```
