List customers with filters

POST /api/users/list/

Python

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())

{
  "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": "[e-mail]",
      "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
    }
  ]
}

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

Authentication

Public API: use an API key.

• Authorization: Bearer YOUR_API_KEY (public API)

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

page · number · default: 1

Page number.

page_size · number · default: 50

The number of customers to return per page. Maximum is 1000.

sort_by · string · default: "-first_seen"

Sort field. Prefix with - for descending.

environment · string · default: "prod"

Filter by environment. Options: prod, test.

POST params

You can add these params to the body:

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)

filters · object

Filters to apply. Supported filter fields include: customer_identifier, name, email, number_of_requests, total_tokens, total_cost, active_days.

Request example

Python

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())

Response

{
  "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": "[e-mail]",
      "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
    }
  ]
}