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

# List End Users

> Retrieve a paginated list of end users

Retrieve a paginated list of end users in your project.

## Authentication

Requires an [API key](/authentication) with `end_users:read` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.bota.dev/v1/end-users?limit=10" \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.bota.dev/v1/end-users?limit=10', {
    headers: {
      'Authorization': 'Bearer sk_live_...',
    },
  });

  const { data, has_more } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.bota.dev/v1/end-users',
      headers={'Authorization': 'Bearer sk_live_...'},
      params={'limit': 10},
  )

  result = response.json()
  end_users = result['data']
  ```
</RequestExample>

## Query Parameters

<ParamField query="limit" type="integer" default="25">
  Maximum number of items to return (1-100).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of items to skip for pagination.
</ParamField>

## Response

Returns a paginated list of end user objects.

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "eu_abc123",
        "external_id": "user_12345",
        "email": "john@example.com",
        "name": "John Doe",
        "metadata": {
          "plan": "pro"
        },
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": "eu_def456",
        "external_id": "user_67890",
        "email": "jane@example.com",
        "name": "Jane Smith",
        "metadata": null,
        "created_at": "2025-01-14T09:00:00Z"
      }
    ],
    "has_more": true
  }
  ```
</ResponseExample>

## Response Fields

| Field      | Type    | Description                                      |
| ---------- | ------- | ------------------------------------------------ |
| `data`     | array   | Array of end user objects.                       |
| `has_more` | boolean | Whether there are more results beyond this page. |

Each end user object in `data` contains:

| Field         | Type   | Description                                               |
| ------------- | ------ | --------------------------------------------------------- |
| `id`          | string | Unique identifier for the end user (prefixed with `eu_`). |
| `external_id` | string | Your system's unique identifier for this user.            |
| `email`       | string | User's email address.                                     |
| `name`        | string | User's display name.                                      |
| `metadata`    | object | Arbitrary key-value metadata.                             |
| `created_at`  | string | ISO 8601 timestamp of when the end user was created.      |