Skip to main content
POST
/
api
/
users
/
list
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": "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
    }
  ]
}

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

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": "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
    }
  ]
}