List customers with filters

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.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod

page number: Page number.
page_size number: The number of customers to return per page. Maximum is 1000.
sort_by string: Sort field. Prefix with - for descending.
environment string: Filter by environment. Options: prod, test.

POST params

You can add these params to the body:

1 url = "https://api.respan.ai/api/users/list/"
2 headers = {
3     "Authorization": "Bearer YOUR_API_KEY",
4 }
5 data = {
6     "filters": {
7         "total_cost": {
8             "operator": "gt",
9             "value": [10.0]
10         }
11     }
12 }
13 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

1 url = "https://api.respan.ai/api/users/list/"
2 headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
3 payload = {
4     "filters": {
5         "email": {"operator": "contains", "value": ["example.com"]},
6     }
7 }
8 
9 resp = requests.post(url, headers=headers, json=payload)
10 print(resp.json())

cURL

$ curl -X POST "https://api.respan.ai/api/users/list/" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "filters": {
>       "email": {
>         "operator": "contains",
>         "value": ["example.com"]
>       }
>     }
>   }'

Response

1 {
2   "count": 51,
3   "next": "https://api.respan.ai/api/users/list/?page=2",
4   "previous": null,
5   "results": [
6     {
7       "id": "user_123prod8264a3f4-40c7-476a-97d1-96908127ea21",
8       "unique_organization_id": "8264a3f4-40c7-476a-97d1-96908127ea21",
9       "customer_identifier": "user_123",
10       "environment": "prod",
11       "name": "John Doe",
12       "email": "john@example.com",
13       "first_seen": "2025-10-15T08:00:00Z",
14       "last_active_timeframe": "2025-12-29T10:30:00Z",
15       "active_days": 75,
16       "number_of_requests": 15420,
17       "total_tokens": 170000,
18       "total_cost": 523.45,
19       "average_latency": 1.23,
20       "average_ttft": 0.45
21     }
22   ]
23 }

List customers with advanced filtering. Use POST when you need complex filters. ## Authentication <Note> Public API: use an API key. - `Authorization: Bearer YOUR_API_KEY` (public API) </Note> 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.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod ``` - `page` *number*: Page number. - `page_size` *number*: The number of customers to return per page. Maximum is 1000. - `sort_by` *string*: Sort field. Prefix with `-` for descending. - `environment` *string*: Filter by environment. Options: `prod`, `test`. ## POST params You can add these params to the **body**: ```python url = "https://api.respan.ai/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 Python url = "https://api.respan.ai/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 curl -X POST "https://api.respan.ai/api/users/list/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filters": { "email": { "operator": "contains", "value": ["example.com"] } } }' ``` ## Response ```json { "count": 51, "next": "https://api.respan.ai/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 } ] } ```

Authentication

AuthorizationBearer

API key authentication. Get your API key from https://platform.respan.ai/platform/api-keys

Query parameters

pagedoubleOptionalDefaults to 1

Page number.

page_sizedoubleOptionalDefaults to 50

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

sort_bystringOptionalDefaults to -first_seen

Sort field. Prefix with - for descending.

environmentstringOptionalDefaults to prod

Filter by environment. Options: prod, test.

Request

This endpoint expects an object.

filtersobjectOptional

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

Response

Successful response for List customers with filters

countinteger

nextstring

previousstring

resultslist of objects

Errors

401

Unauthorized Error

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.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod

page number: Page number.
page_size number: The number of customers to return per page. Maximum is 1000.
sort_by string: Sort field. Prefix with - for descending.
environment string: Filter by environment. Options: prod, test.

POST params

You can add these params to the body:

1 url = "https://api.respan.ai/api/users/list/"
2 headers = {
3     "Authorization": "Bearer YOUR_API_KEY",
4 }
5 data = {
6     "filters": {
7         "total_cost": {
8             "operator": "gt",
9             "value": [10.0]
10         }
11     }
12 }
13 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

1 url = "https://api.respan.ai/api/users/list/"
2 headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
3 payload = {
4     "filters": {
5         "email": {"operator": "contains", "value": ["example.com"]},
6     }
7 }
8 
9 resp = requests.post(url, headers=headers, json=payload)
10 print(resp.json())

cURL

$ curl -X POST "https://api.respan.ai/api/users/list/" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "filters": {
>       "email": {
>         "operator": "contains",
>         "value": ["example.com"]
>       }
>     }
>   }'

Response

1 {
2   "count": 51,
3   "next": "https://api.respan.ai/api/users/list/?page=2",
4   "previous": null,
5   "results": [
6     {
7       "id": "user_123prod8264a3f4-40c7-476a-97d1-96908127ea21",
8       "unique_organization_id": "8264a3f4-40c7-476a-97d1-96908127ea21",
9       "customer_identifier": "user_123",
10       "environment": "prod",
11       "name": "John Doe",
12       "email": "john@example.com",
13       "first_seen": "2025-10-15T08:00:00Z",
14       "last_active_timeframe": "2025-12-29T10:30:00Z",
15       "active_days": 75,
16       "number_of_requests": 15420,
17       "total_tokens": 170000,
18       "total_cost": 523.45,
19       "average_latency": 1.23,
20       "average_ttft": 0.45
21     }
22   ]
23 }

1	curl -X POST https://api.respan.ai/api/users/list/ \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{}'

1	url = "https://api.respan.ai/api/users/list/"
2	headers = {
3	"Authorization": "Bearer YOUR_API_KEY",
4	}
5	data = {
6	"filters": {
7	"total_cost": {
8	"operator": "gt",
9	"value": [10.0]
10	}
11	}
12	}
13	response = requests.post(url, headers=headers, json=data)

1	url = "https://api.respan.ai/api/users/list/"
2	headers = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
3	payload = {
4	"filters": {
5	"email": {"operator": "contains", "value": ["example.com"]},
6	}
7	}
8
9	resp = requests.post(url, headers=headers, json=payload)
10	print(resp.json())

$	curl -X POST "https://api.respan.ai/api/users/list/" \
>	-H "Authorization: Bearer YOUR_API_KEY" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"filters": {
>	"email": {
>	"operator": "contains",
>	"value": ["example.com"]
>	}
>	}
>	}'

1	{
2	"count": 51,
3	"next": "https://api.respan.ai/api/users/list/?page=2",
4	"previous": null,
5	"results": [
6	{
7	"id": "user_123prod8264a3f4-40c7-476a-97d1-96908127ea21",
8	"unique_organization_id": "8264a3f4-40c7-476a-97d1-96908127ea21",
9	"customer_identifier": "user_123",
10	"environment": "prod",
11	"name": "John Doe",
12	"email": "john@example.com",
13	"first_seen": "2025-10-15T08:00:00Z",
14	"last_active_timeframe": "2025-12-29T10:30:00Z",
15	"active_days": 75,
16	"number_of_requests": 15420,
17	"total_tokens": 170000,
18	"total_cost": 523.45,
19	"average_latency": 1.23,
20	"average_ttft": 0.45
21	}
22	]
23	}