Read one proposed change

GET
/v1/agents/{id}/proposals/{pid}

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.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The agent id.

pid*string

The proposal id.

Response Body

The proposal, what it changes, and after shipping the live before and after

application/json
  1. response
proposal*
diff*array<>
live*|null
problemName*string|null
problemMiss*|
Value in"misunderstood""missing_information""could_not_act""stuck""out_of_scope""handed_off""contact_left""not_reached""other"null
Example Request
curl "https://api.vlayers.ai/v1/agents/$AGENT_ID/proposals/$PROPOSAL_ID" \  -H "Authorization: Bearer $VOICELAYER_API_KEY"
Example Response
{  "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"}