List customers | Respan Docs

The Users List endpoint allows you to retrieve customers with pagination and sorting.

Authentication

Use your Respan API key in Authorization: Bearer YOUR_API_KEY.

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.

Examples: customer_identifier, -total_cost, email, -number_of_requests.
environment string: Filter by environment. Options: prod, test.

Request example

Python

1 from urllib.parse import urlencode
2 
3 base_url = "https://api.respan.ai/api/users/list/"
4 params = {
5     "page": 1,
6     "page_size": 50,
7     "sort_by": "-first_seen",
8     "environment": "prod",
9 }
10 url = f"{base_url}?{urlencode(params)}"
11 headers = {"Authorization": "Bearer YOUR_API_KEY"}
12 
13 response = requests.get(url, headers=headers)
14 print(response.json())

cURL

$ curl "https://api.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod" \
>   -H "Authorization: Bearer YOUR_API_KEY"

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 }

The Users List endpoint allows you to retrieve customers with pagination and sorting. ## Authentication <Note>Use your Respan API key in `Authorization: Bearer YOUR_API_KEY`.</Note> ## 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. Examples: `customer_identifier`, `-total_cost`, `email`, `-number_of_requests`. - `environment` *string*: Filter by environment. Options: `prod`, `test`. ## Request example ```python Python from urllib.parse import urlencode base_url = "https://api.respan.ai/api/users/list/" params = { "page": 1, "page_size": 50, "sort_by": "-first_seen", "environment": "prod", } url = f"{base_url}?{urlencode(params)}" headers = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` ```bash cURL curl "https://api.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## 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. Examples: customer_identifier, -total_cost, email, -number_of_requests.

environmentstringOptionalDefaults to prod

Filter by environment. Options: prod, test.

Response

Successful response for List customers

countinteger

nextstring

previousstring

resultslist of objects

Errors

401

Unauthorized Error

The Users List endpoint allows you to retrieve customers with pagination and sorting.

Authentication

Use your Respan API key in Authorization: Bearer YOUR_API_KEY.

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.

Examples: customer_identifier, -total_cost, email, -number_of_requests.
environment string: Filter by environment. Options: prod, test.

Request example

Python

1 from urllib.parse import urlencode
2 
3 base_url = "https://api.respan.ai/api/users/list/"
4 params = {
5     "page": 1,
6     "page_size": 50,
7     "sort_by": "-first_seen",
8     "environment": "prod",
9 }
10 url = f"{base_url}?{urlencode(params)}"
11 headers = {"Authorization": "Bearer YOUR_API_KEY"}
12 
13 response = requests.get(url, headers=headers)
14 print(response.json())

cURL

$ curl "https://api.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod" \
>   -H "Authorization: Bearer YOUR_API_KEY"

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	from urllib.parse import urlencode
2
3	base_url = "https://api.respan.ai/api/users/list/"
4	params = {
5	"page": 1,
6	"page_size": 50,
7	"sort_by": "-first_seen",
8	"environment": "prod",
9	}
10	url = f"{base_url}?{urlencode(params)}"
11	headers = {"Authorization": "Bearer YOUR_API_KEY"}
12
13	response = requests.get(url, headers=headers)
14	print(response.json())

$	curl "https://api.respan.ai/api/users/list/?page=1&page_size=50&sort_by=-first_seen&environment=prod" \
>	-H "Authorization: Bearer YOUR_API_KEY"

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	}