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

# Get a vault session

> Read a session until the user finishes. The poll alternative to the vault.session_linked webhook.

**id** `string` *required*

The `id` from the create response. Not the `vs=` token inside `url`.

```bash cURL theme={null}
curl https://api.agentcard.sh/api/v2/vault_sessions/vs_2q9d1x8f3k2m4t7w \
  -H "Authorization: Bearer $ORG_TOKEN"
```

```json 200 theme={null}
{
  "object": "vault_session",
  "id": "vs_2q9d1x8f3k2m4t7w",
  "status": "linked",
  "user_id": "usr_8f3k2m",
  "linked_at": "2026-09-02T18:41:07Z",
  "poll_interval": 3,
  "code_sends": null,
  "verify_attempts": null,
  "channel": null,
  "expires_at": "2026-09-03T18:00:00Z",
  "created_at": "2026-09-02T18:00:00Z",
  "test_mode": false
}
```

**status** `string`

`pending` (wait `poll_interval` seconds and read again), `linked` (store `user_id`, stop), or `expired` (create a new session).

**user\_id** `string | null`

The id to store once `linked`. A connected session carries it from the start.

**code\_sends** `number | null`

How many times a connected user asked for their code. Null on open sessions.

**verify\_attempts** `number | null`

How many codes a connected user tried. Null on open sessions.

**payment\_permission** `object`

Only on a session that asked for app auto-approval. Whether your app can pay with the card the user gave it: `card_id`, `grant_id`, `revision`, `status` (`pending`, `active`, `revoked`, `retired`, or `unavailable`), and `ready`. Poll until `ready` is `true`. See [Enable auto-approval](/vault/app-auto-approval).

**Budget.** 40 reads a minute per session, 600 a minute across your account. Honor `poll_interval` and you never see a `429`. Only the client that created the session can read it; anything else is a `404`.


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