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

# List vaults

> List vaults under the current account with cursor pagination and optional search.

`GET /api/v1/cloud/vaults`

Retrieves vaults under the current account with cursor pagination and optional name search. Archived vaults are excluded by default.

## Headers

| Header          | Required | Description         |
| --------------- | -------- | ------------------- |
| `Authorization` | Yes      | `Bearer $QODER_PAT` |

## Query parameters

| Parameter          | Type    | Required | Description                                                                                                       |
| ------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `limit`            | integer | No       | Maximum number of records per page. Default 20, range 1-100. Values above 100 return `400 invalid_request_error`. |
| `page`             | string  | No       | Claude-style forward cursor. Equivalent to `after_id`; mutually exclusive with `before_id` and `after_id`         |
| `after_id`         | string  | No       | Cursor pagination: return records after this ID. Mutually exclusive with `page` and `before_id`                   |
| `before_id`        | string  | No       | Cursor pagination: return records before this ID. Mutually exclusive with `page` and `after_id`                   |
| `include_archived` | boolean | No       | Set to `true` to include archived vaults                                                                          |
| `name`             | string  | No       | Search vaults by display name                                                                                     |

## Example request

```bash theme={null}
# List all vaults
curl -X GET https://api.qoder.com/api/v1/cloud/vaults \
  -H "Authorization: Bearer $QODER_PAT"

# Paginate
curl -X GET "https://api.qoder.com/api/v1/cloud/vaults?limit=2" \
  -H "Authorization: Bearer $QODER_PAT"

# Search by name, including archived vaults
curl -X GET "https://api.qoder.com/api/v1/cloud/vaults?name=my-mcp&include_archived=true" \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "vault_019e3bb940277f0db05ab74291acf6ef",
      "type": "vault",
      "display_name": "my-mcp-vault",
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-18T15:34:16.874877Z",
      "updated_at": "2026-05-18T15:34:16.874877Z"
    }
  ],
  "next_page": null,
  "first_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "last_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "has_more": false
}
```

### Empty list response

```json theme={null}
{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## Response fields

| Field       | Type           | Description                                                               |
| ----------- | -------------- | ------------------------------------------------------------------------- |
| `data`      | array          | Array of [Vault objects](/cloud-agents/api/vaults/schemas#vault-object)   |
| `next_page` | string \| null | Forward cursor for the next page; use as `page` when `has_more` is `true` |
| `first_id`  | string \| null | ID of the first record on the current page                                |
| `last_id`   | string \| null | ID of the last record on the current page (use for cursor pagination)     |
| `has_more`  | boolean        | Whether more pages are available                                          |

## Errors

| HTTP | Type                    | Trigger                                                                              |
| ---- | ----------------------- | ------------------------------------------------------------------------------------ |
| 400  | `invalid_request_error` | Invalid `limit`, or more than one of `page`, `before_id`, and `after_id` is provided |
| 401  | `TOKEN_INVALID`         | Missing or invalid authentication token                                              |

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

## Related

<CardGroup cols={2}>
  <Card title="Authenticate with vaults" icon="key" href="/cloud-agents/vaults">
    Store and inject secrets safely into agent sessions.
  </Card>
</CardGroup>