---
title: "List users"
method: POST
path: "/api/users/list/"
tags: ["Users"]
---

# List users

`POST /api/users/list/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/users/list/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Returns users in your organization with usage analytics and budget settings. Filter fields include `customer_identifier`, `name`, `email`, `number_of_requests`, `total_tokens`, `total_cost`, and `active_days`.

## Query parameters

- `page` integer
- `page_size` integer
- `sort_by` string
- `environment` 'prod' | 'test'

## Request body

- object
  - `filters` Filters: Each key is a field to filter on, and each value is a condition: `{"<field>": {"operator": "<operator>", "value": [...]}}`. A result must match every condition. To set two conditions on one field, such as a range, pass a list of conditions. **Operators:** `""` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `""` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[""]`. The fields you can filter on depend on the endpoint; `metadata__<key>` filters custom metadata where the endpoint supports it.
    - `status` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `status_code` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `unique_id` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `customer_identifier` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `thread_identifier` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `custom_identifier` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `group_identifier` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `prompt_id` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `trace_unique_id` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `span_parent_id` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `is_root_span` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `span_workflow_name` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `span_name` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `model` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `log_type` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `stream` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `has_tool_calls` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `cache_bit` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `cache_key` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `prompt_tokens` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `completion_tokens` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `total_tokens` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `cost` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `latency` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown
    - `positive_feedback` FilterValue: A filter condition with an operator and value.
      - `operator` '' | 'not' | 'in' | 'not_in' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'not_contains' | 'icontains' | 'startswith' | 'not_startswith' | 'endswith' | 'not_endswith' | 'empty' | 'not_empty': Comparison operator. An empty string means equals.
      - `value` unknown[], required: Value(s) to filter by.
        - unknown

## Response `200`

Paginated list of users.

- object
  - `count` integer, required: Number of results on this page, not the total. Request pages until `next` is null to get every result.
  - `next` string, nullable: Next page URL.
  - `previous` string, nullable: Previous page URL.
  - `results` object[], required: Users for the current page.
    - `id` string: Synthetic user ID returned in lists.
    - `customer_identifier` string: Your unique identifier for the user.
    - `unique_organization_id` string: Organization unique ID.
    - `environment` 'prod' | 'test': User environment.
    - `name` string, nullable: User display name.
    - `email` string, nullable: User email address.
    - `first_seen` string, date-time: When the user was first observed.
    - `last_active_timeframe` string, date-time: Most recent activity within the selected timeframe.
    - `active_days` integer: Number of active days in the selected timeframe.
    - `number_of_requests` integer: Total requests made by this user.
    - `total_requests` integer: Alias of `number_of_requests` for backward compatibility.
    - `total_tokens` integer: Total tokens used by this user.
    - `tokens` integer: Alias of `total_tokens` for backward compatibility.
    - `total_cost` number: Total cost in USD.
    - `cost` number: Alias of `total_cost` for backward compatibility.
    - `average_latency` number, nullable: Average latency in seconds.
    - `average_ttft` number, nullable: Average time to first token in seconds.
    - `average_monthly_cost` number: Estimated average monthly cost based on observed activity.
    - `period_budget` number, nullable: Current period budget in USD, when configured.
    - `budget_duration` 'daily' | 'weekly' | 'monthly': Budget renewal period.
    - `total_budget` number, nullable: Lifetime spending budget in USD, when configured.

## Other responses

- `400`: Bad Request
- `403`: The API key is missing, invalid or expired.
- `413`: The query exceeded a memory or execution-time resource limit.
- `429`: Rate Limited
- `500`: Internal Server Error

## Changes

- **2026-10-21** `c30bcb383ee8`: 16 breaking, 4 info
  - request body became required
  - the response property `next` became nullable for the status `200`
  - the response property `previous` became nullable for the status `200`
  - the response property `results/items/average_latency` became nullable for the status `200`
  - …16 more
- **2026-10-02** `b830b79cfd52`: 46 breaking, 5 warning, 142 info
  - removed the enum value `iexact` of the request property `filters/cache_key/operator`
  - removed the enum value `iexact` of the request property `filters/completion_tokens/operator`
  - removed the enum value `iexact` of the request property `filters/cost/operator`
  - removed the enum value `iexact` of the request property `filters/custom_identifier/operator`
  - …189 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `list-customers` removed and replaced with `users_listCustomers`
- **2026-08-22** `b18c72975097`: 1 warning
  - for the `query` request parameter `page_size`, the max was set to `1000.00`

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/users/list/post.md)

---

[API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)