Read a share link
Reads one share link with its recent refusals and stops: why a visit was turned away or a conversation ended (expired, revoked, conversations_used, minutes_used, budget_used, busy and the others), each with when and how many times in a row. Use it to see why a link stopped working, and send its version as If-Match when you change it.
Requires an API key with the share_links:read scope.
apiKeyAuthorizationBearer <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.
linkId*stringThe share link id, from the list or from the answer that made it.
The link with its recent refusals and stops
application/json- response
id*stringThe link id.
agentId*stringThe agent the link opens.
uuidstate*stringactive, expired or revoked (turned off).
"active""expired""revoked"title*stringdisplayName*stringtarget*stringlive: the published version of the agent. draft: its draft as it is now. The link keeps the version it was made from until you update it.
"live""draft"sealedVersionLabel*stringWhat version the link runs, in words: "Published version of Nov 8" or "Draft of Nov 8, 3:12 pm".
sealedAt*stringdate-timeprivacyUrl*stringlimits*The nine caps of the link.
expiresAt*stringdate-timetools*Which tools the link has off. Tools that send, call or transfer to a destination from the conversation are always off.
usage*lastUsedAt*|date-timerevokedBy*|Who turned it off, when it was.
revokedAt*|date-timecreatedBy*stringcreatedAt*stringdate-timeupdatedAt*stringdate-timeversion*integerSend this back as If-Match when you change the link. A stale one is refused with 409.
behindPublishedReason?|Set when the link runs an older version than the agent publishes now, and says why it was not moved. Change the link to update it.
recent*array<>Recent refusals and stops, newest first.
items <= 50curl "https://api.vlayers.ai/v1/share-links/$SHARE_LINK_ID" \ -H "Authorization: Bearer $VOICELAYER_API_KEY"{ "id": "grt_0192f5e1a2b37c4d8e5f6a7b8c9d0e1f", "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78", "state": "active", "title": "Books team test", "displayName": "Acme Books", "target": "live", "sealedVersionLabel": "Published version of Nov 8", "sealedAt": "2026-11-08T15:12:00.000Z", "privacyUrl": "https://acmebooks.example/privacy", "limits": { "conversations": 20, "voiceMinutes": 60, "dollarsMicros": 10000000, "atOnce": 2, "callMinutes": 5, "typedMessages": 40, "typedDollarsMicros": 1000000, "perAddressPerDay": 5, "perAddressPerHour": 3 }, "expiresAt": "2026-11-15T15:12:00.000Z", "tools": { "off": [ "refund_order", "vl_send_text" ] }, "usage": { "conversations": 3, "minutes": 12.5, "spentMicros": 1500000 }, "lastUsedAt": "2026-11-09T09:30:00.000Z", "revokedBy": null, "revokedAt": null, "createdBy": "user_2abc", "createdAt": "2026-11-08T15:12:00.000Z", "updatedAt": "2026-11-08T15:12:00.000Z", "version": 3, "recent": [ { "reason": "busy", "at": "2026-11-09T09:31:00.000Z", "count": 2 } ]}