> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/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.

<ParamField path="id" type="string" required>The `id` from the create response. Not the `vs=` token inside `url`.</ParamField>

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

<ResponseExample>
  ```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
  }
  ```
</ResponseExample>

<ResponseField name="status" type="string">`pending` (wait `poll_interval` seconds and read again), `linked` (store `user_id`, stop), or `expired` (create a new session).</ResponseField>
<ResponseField name="user_id" type="string | null">The id to store once `linked`. A connected session carries it from the start.</ResponseField>
<ResponseField name="code_sends" type="number | null">How many times a connected user asked for their code. Null on open sessions.</ResponseField>
<ResponseField name="verify_attempts" type="number | null">How many codes a connected user tried. Null on open sessions.</ResponseField>

**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`.