# GET /v1/users

> List your users.

In [Users API](https://vestra.ai/developers/reference/api/users.md): Your users: set one up, read their spend, change their cap, export or erase them.

Send `Authorization: Bearer vk_test_...` on every call.

List your users.

Your API key, scope `runtime` or `all`. On the card: [`users`](https://vestra.ai/developers/users.md). Over HTTP it is made from the contract: fill in every value.

## Request

Query:

- `limit` (`integer`): How many items per page, 1 to 100. Default 20.
- `cursor` (`string`): Where to go on from: the `next_cursor` of the page before, unchanged. Absent: the first page.

## Answers 200

- `data` (`object[]`): The items on this page.
  - `id` (`string`): Your own id for the user. Example: `traveller-42`.
  - `object` (`"user"`): Always user.
  - `name` (`string | null`): The user's name; null when you gave none.
  - `email` (`string | null`): The user's email address; null when you gave none.
  - `locale` (`string | null`): The user's language and region (BCP 47); null when you gave none.
  - `timezone` (`string | null`): The user's time zone (IANA); null when you gave none, and their routines then run in UTC.
  - `metadata` (`map of any`): Your own facts about the user; empty when you gave none.
  - `status` (`"active" | "disabled"`): active, or disabled: a disabled user's calls are refused (403 user_disabled) until you turn them back on.
  - `spend_cap_usd` (`number | null`): The user's own cap per day, in billed US dollars, never above your company's; null: your company's cap for each user, if any.
  - `monthly_cap_usd` (`number | null`): The user's own cap per calendar month (UTC), in billed US dollars; null: your company's cap for each user, if any.
  - `default_deployment` (`string | null`): The deployment their conversations use when none is named (dep_...); null: your company's default.
  - `memory_mode` (`"vestra" | "customer" | "none"`): Where Bash's memory of this user lives: `vestra`, `customer` (your memory endpoint), or `none`.
  - `is_service_user` (`boolean`): true for a user Vestra keeps for itself, such as your company's own Bash; false for your users.
  - `created_at` (`string`): When the user was made, as an ISO 8601 time.
- `next_cursor` (`string | null`): Send it as `cursor` for the next page; null on the last page.

## Code

**TypeScript**

```ts
const users = await vestra.users.list();
```

**Python**

```python
users = vestra.users.list()
```

**CLI**

```bash
vestra users
```

**HTTP**

```bash
curl "$VESTRA_BASE_URL/v1/users" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

**MCP**: No sample in your language for this route, so here it is over HTTP.