# Read one proposed change

Source: https://docs.vlayers.ai/reference/agents/get-agent-proposal

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

One proposed change: what it changes in the prompt, the replays on the published version and on the draft, the cost per successful conversation, whether it widens what the agent can do, who decided and how. After it ships it also carries the live goal rate before and after.

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"` |
| `pid` | path | string | yes | The proposal id. Example: `"0192f5fe-2736-7184-8d34-56789abcdef0"` |

## Request

cURL:

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

TypeScript:

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

const voicelayer = new VoiceLayer();

const { proposal } = await voicelayer.agents.getProposal('<agent-id>', '<proposal-id>');
console.log(proposal.status);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.agents.get_proposal("<agent-id>", "<proposal-id>")
print(result.proposal.status)
```

## Response `200`

```json
{
  "proposal": {
    "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"
  },
  "diff": [
    {
      "field": "systemPrompt",
      "before": "You are the booking assistant.",
      "after": "You are the booking assistant. When asked about availability, check it before answering."
    }
  ],
  "live": null,
  "problemName": "Did not have the answer at 'Check availability'",
  "problemMiss": "missing_information"
}
```
