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

# List customers with filters

List customers with advanced filtering. Use POST when you need complex filters.

## Authentication

<Info>
  Public API: use an API key.

  * `Authorization: Bearer YOUR_API_KEY` (public API)
</Info>

The Users List endpoint allows you to list customers with advanced filtering using POST.

## Query params

You can add these params to the **URL params**.
For example:

```
https://api.keywordsai.co/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod
```

<ParamField query="page" type="number" default={1}>
  Page number.
</ParamField>

<ParamField query="page_size" type="number" default={50}>
  The number of customers to return per page. Maximum is 1000.
</ParamField>

<ParamField query="sort_by" type="string" default="-first_seen">
  Sort field. Prefix with `-` for descending.
</ParamField>

<ParamField query="environment" type="string" default="prod">
  Filter by environment. Options: `prod`, `test`.
</ParamField>

## POST params

You can add these params to the **body**:

```python theme={"system"}
url = "https://api.keywordsai.co/api/users/list/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
data = {
    "filters": {
        "total_cost": {
            "operator": "gt",
            "value": [10.0]
        }
    }
}
response = requests.post(url, headers=headers, json=data)
```

<ParamField body="filters" type="object" default={{}}>
  Filters to apply. Supported filter fields include:
  `customer_identifier`, `name`, `email`, `number_of_requests`, `total_tokens`, `total_cost`, `active_days`.
</ParamField>

## Request example

<RequestExample>
  ```python Python theme={"system"}
  import requests

  url = "https://api.keywordsai.co/api/users/list/"
  headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
  payload = {
      "filters": {
          "email": {"operator": "contains", "value": ["example.com"]},
      }
  }

  resp = requests.post(url, headers=headers, json=payload)
  print(resp.json())
  ```

  ```bash cURL theme={"system"}
  curl -X POST "https://api.keywordsai.co/api/users/list/" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filters": {
        "email": {
          "operator": "contains",
          "value": ["example.com"]
        }
      }
    }'
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json theme={"system"}
  {
    "count": 51,
    "next": "https://api.keywordsai.co/api/users/list/?page=2",
    "previous": null,
    "results": [
      {
        "id": "user_123prod8264a3f4-40c7-476a-97d1-96908127ea21",
        "unique_organization_id": "8264a3f4-40c7-476a-97d1-96908127ea21",
        "customer_identifier": "user_123",
        "environment": "prod",
        "name": "John Doe",
        "email": "john@example.com",
        "first_seen": "2025-10-15T08:00:00Z",
        "last_active_timeframe": "2025-12-29T10:30:00Z",
        "active_days": 75,
        "number_of_requests": 15420,
        "total_tokens": 170000,
        "total_cost": 523.45,
        "average_latency": 1.23,
        "average_ttft": 0.45
      }
    ]
  }
  ```
</ResponseExample>