Skip to Content

List users

POSThttps://api.respan.ai/api/users/list/

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.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Query parameters

Parameter Type Required Description and constraints
page integer Optional
Page number.
Default: 1
Example: 1
page_size integer Optional
Number of users per page. Maximum is 1000.
Default: 50
Maximum: 1000
Example: 50
sort_by string Optional
Sort field. Prefix with - for descending. Common values include customer_identifier, email, name, -first_seen, -number_of_requests, and -total_cost.
Default: -first_seen
Example: "-total_cost"
environment string Optional
Optional environment filter. If omitted, the backend uses the environment implied by your auth context when applicable.
Allowed: "prod", "test"
Example: "prod"

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
-
filters object Optional
Each key is a field to filter on, and each value is a condition: {"<field>": {"operator": "<operator>", "value": [...]}}. A user 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 [""].

Fields: customer_identifier, name, email, environment, number_of_requests, total_cost, total_tokens, total_prompt_tokens, total_completion_tokens, average_latency, average_ttft, active_days. Unsupported fields, including metadata__<key>, return a 400 error.

Example:

json<br />{<br /> "total_cost": {"operator": "gte", "value": [10]},<br /> "email": {"operator": "endswith", "value": ["@acme.dev"]}<br />}<br />
Reference: #/components/schemas/Filters
Example: {"customer_identifier":{"operator":"","value":["alex@acme.dev"]}}
filters.status object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.status.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.status.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.status.value[] any Array item
-
filters.status_code object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.status_code.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.status_code.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.status_code.value[] any Array item
-
filters.unique_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.unique_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.unique_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.unique_id.value[] any Array item
-
filters.customer_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.customer_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.customer_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.customer_identifier.value[] any Array item
-
filters.thread_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.thread_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.thread_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.thread_identifier.value[] any Array item
-
filters.custom_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.custom_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.custom_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.custom_identifier.value[] any Array item
-
filters.group_identifier object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.group_identifier.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.group_identifier.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.group_identifier.value[] any Array item
-
filters.prompt_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.prompt_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.prompt_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.prompt_id.value[] any Array item
-
filters.trace_unique_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.trace_unique_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.trace_unique_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.trace_unique_id.value[] any Array item
-
filters.span_parent_id object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.span_parent_id.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.span_parent_id.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.span_parent_id.value[] any Array item
-
filters.is_root_span object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.is_root_span.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.is_root_span.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.is_root_span.value[] any Array item
-
filters.span_workflow_name object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.span_workflow_name.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.span_workflow_name.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.span_workflow_name.value[] any Array item
-
filters.span_name object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.span_name.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.span_name.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.span_name.value[] any Array item
-
filters.model object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.model.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.model.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.model.value[] any Array item
-
filters.log_type object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.log_type.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.log_type.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.log_type.value[] any Array item
-
filters.stream object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.stream.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.stream.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.stream.value[] any Array item
-
filters.has_tool_calls object Optional
Whether the span made tool calls.
Reference: #/components/schemas/FilterValue
filters.has_tool_calls.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.has_tool_calls.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.has_tool_calls.value[] any Array item
-
filters.cache_bit object Optional
Whether the response was served from the Respan cache.
Reference: #/components/schemas/FilterValue
filters.cache_bit.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.cache_bit.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.cache_bit.value[] any Array item
-
filters.cache_key object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.cache_key.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.cache_key.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.cache_key.value[] any Array item
-
filters.prompt_tokens object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.prompt_tokens.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.prompt_tokens.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.prompt_tokens.value[] any Array item
-
filters.completion_tokens object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.completion_tokens.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.completion_tokens.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.completion_tokens.value[] any Array item
-
filters.total_tokens object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.total_tokens.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.total_tokens.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.total_tokens.value[] any Array item
-
filters.cost object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.cost.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.cost.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.cost.value[] any Array item
-
filters.latency object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.latency.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.latency.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.latency.value[] any Array item
-
filters.positive_feedback object Optional
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.positive_feedback.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.positive_feedback.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.positive_feedback.value[] any Array item
-
filters.<key> object Map value
A filter condition with an operator and value.
Reference: #/components/schemas/FilterValue
filters.<key>.operator string Optional
Comparison operator. An empty string means equals.
Allowed: "", "not", "in", "not_in", "lt", "lte", "gt", "gte", "contains", "not_contains", "icontains", "startswith", "not_startswith", "endswith", "not_endswith", "empty", "not_empty"
Default: “
Example: "gte"
filters.<key>.value array<any> Required in parent
Value(s) to filter by.
Example: [0.01]
filters.<key>.value[] any Array item
-

OpenAPI request schema

{
  "type": "object",
  "properties": {
    "filters": {
      "$ref": "#/components/schemas/Filters",
      "description": "Each key is a field to filter on, and each value is a condition: `{\"<field>\": {\"operator\": \"<operator>\", \"value\": [...]}}`. A user must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.\n\n**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 `[\"\"]`.\n\n**Fields:** `customer_identifier`, `name`, `email`, `environment`, `number_of_requests`, `total_cost`, `total_tokens`, `total_prompt_tokens`, `total_completion_tokens`, `average_latency`, `average_ttft`, `active_days`. Unsupported fields, including `metadata__<key>`, return a 400 error.\n\n**Example:**\n\n```json\n{\n  \"total_cost\": {\"operator\": \"gte\", \"value\": [10]},\n  \"email\": {\"operator\": \"endswith\", \"value\": [\"@acme.dev\"]}\n}\n```"
    }
  }
}
Example
JSON
{ "filters": { "total_cost": { "operator": "gte", "value": [ 10 ] }, "email": { "operator": "contains", "value": [ "example.com" ] } } }

Responses

200

Paginated list of users.

application/json

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

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Number of results on this page, not the total. Request pages until `next` is null to get every result."
    },
    "next": {
      "type": "string",
      "nullable": true,
      "description": "Next page URL."
    },
    "previous": {
      "type": "string",
      "nullable": true,
      "description": "Previous page URL."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Synthetic user ID returned in lists."
          },
          "customer_identifier": {
            "type": "string",
            "description": "Your unique identifier for the user."
          },
          "unique_organization_id": {
            "type": "string",
            "description": "Organization unique ID."
          },
          "environment": {
            "type": "string",
            "enum": [
              "prod",
              "test"
            ],
            "description": "User environment."
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "User display name."
          },
          "email": {
            "type": "string",
            "nullable": true,
            "description": "User email address."
          },
          "first_seen": {
            "type": "string",
            "format": "date-time",
            "description": "When the user was first observed."
          },
          "last_active_timeframe": {
            "type": "string",
            "format": "date-time",
            "description": "Most recent activity within the selected timeframe."
          },
          "active_days": {
            "type": "integer",
            "description": "Number of active days in the selected timeframe."
          },
          "number_of_requests": {
            "type": "integer",
            "description": "Total requests made by this user."
          },
          "total_requests": {
            "type": "integer",
            "description": "Alias of `number_of_requests` for backward compatibility."
          },
          "total_tokens": {
            "type": "integer",
            "description": "Total tokens used by this user."
          },
          "tokens": {
            "type": "integer",
            "description": "Alias of `total_tokens` for backward compatibility."
          },
          "total_cost": {
            "type": "number",
            "description": "Total cost in USD."
          },
          "cost": {
            "type": "number",
            "description": "Alias of `total_cost` for backward compatibility."
          },
          "average_latency": {
            "type": "number",
            "nullable": true,
            "description": "Average latency in seconds."
          },
          "average_ttft": {
            "type": "number",
            "nullable": true,
            "description": "Average time to first token in seconds."
          },
          "average_monthly_cost": {
            "type": "number",
            "description": "Estimated average monthly cost based on observed activity."
          },
          "period_budget": {
            "type": "number",
            "nullable": true,
            "description": "Current period budget in USD, when configured."
          },
          "budget_duration": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly"
            ],
            "description": "Budget renewal period."
          },
          "total_budget": {
            "type": "number",
            "nullable": true,
            "description": "Lifetime spending budget in USD, when configured."
          }
        }
      },
      "description": "Users for the current page."
    }
  },
  "required": [
    "count",
    "results"
  ]
}
Example
JSON
{ "count": 51, "next": "https://api.respan.ai/api/users/list/?page=2", "previous": null, "results": [ { "id": "user_123prod8264a3f4-40c7-476a-97d1-96908127ea21", "customer_identifier": "user_123", "unique_organization_id": "8264a3f4-40c7-476a-97d1-96908127ea21", "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_requests": 15420, "total_tokens": 170000, "tokens": 170000, "total_cost": 523.45, "cost": 523.45, "average_latency": 1.23, "average_ttft": 0.45, "average_monthly_cost": 6.98, "period_budget": 100, "budget_duration": "monthly", "total_budget": 1000 } ] }

400

Bad Request

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Invalid filters payload."

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Invalid filters payload."
    }
  }
}

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

413

The query exceeded a memory or execution-time resource limit.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "This query is too large to run — it exceeded a per-query resource limit. Narrow the time range or add filters, then try again." }

429

Rate Limited

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Request was throttled. Expected available in 1 second."

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Request was throttled. Expected available in 1 second."
    }
  }
}

500

Internal Server Error

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Internal server error"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Internal server error"
    }
  }
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "List users",
  "operationId": "listCustomers",
  "tags": [
    "Users"
  ],
  "description": "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`.",
  "parameters": [
    {
      "name": "page",
      "in": "query",
      "schema": {
        "type": "integer",
        "default": 1
      },
      "description": "Page number.",
      "example": 1
    },
    {
      "name": "page_size",
      "in": "query",
      "schema": {
        "type": "integer",
        "default": 50,
        "maximum": 1000
      },
      "description": "Number of users per page. Maximum is 1000.",
      "example": 50
    },
    {
      "name": "sort_by",
      "in": "query",
      "schema": {
        "type": "string",
        "default": "-first_seen"
      },
      "description": "Sort field. Prefix with `-` for descending. Common values include `customer_identifier`, `email`, `name`, `-first_seen`, `-number_of_requests`, and `-total_cost`.",
      "example": "-total_cost"
    },
    {
      "name": "environment",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "prod",
          "test"
        ]
      },
      "description": "Optional environment filter. If omitted, the backend uses the environment implied by your auth context when applicable.",
      "example": "prod"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "filters": {
              "$ref": "#/components/schemas/Filters",
              "description": "Each key is a field to filter on, and each value is a condition: `{\"<field>\": {\"operator\": \"<operator>\", \"value\": [...]}}`. A user must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.\n\n**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 `[\"\"]`.\n\n**Fields:** `customer_identifier`, `name`, `email`, `environment`, `number_of_requests`, `total_cost`, `total_tokens`, `total_prompt_tokens`, `total_completion_tokens`, `average_latency`, `average_ttft`, `active_days`. Unsupported fields, including `metadata__<key>`, return a 400 error.\n\n**Example:**\n\n```json\n{\n  \"total_cost\": {\"operator\": \"gte\", \"value\": [10]},\n  \"email\": {\"operator\": \"endswith\", \"value\": [\"@acme.dev\"]}\n}\n```"
            }
          }
        },
        "example": {
          "filters": {
            "total_cost": {
              "operator": "gte",
              "value": [
                10
              ]
            },
            "email": {
              "operator": "contains",
              "value": [
                "example.com"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Paginated list of users.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of results on this page, not the total. Request pages until `next` is null to get every result."
              },
              "next": {
                "type": "string",
                "nullable": true,
                "description": "Next page URL."
              },
              "previous": {
                "type": "string",
                "nullable": true,
                "description": "Previous page URL."
              },
              "results": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Synthetic user ID returned in lists."
                    },
                    "customer_identifier": {
                      "type": "string",
                      "description": "Your unique identifier for the user."
                    },
                    "unique_organization_id": {
                      "type": "string",
                      "description": "Organization unique ID."
                    },
                    "environment": {
                      "type": "string",
                      "enum": [
                        "prod",
                        "test"
                      ],
                      "description": "User environment."
                    },
                    "name": {
                      "type": "string",
                      "nullable": true,
                      "description": "User display name."
                    },
                    "email": {
                      "type": "string",
                      "nullable": true,
                      "description": "User email address."
                    },
                    "first_seen": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the user was first observed."
                    },
                    "last_active_timeframe": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Most recent activity within the selected timeframe."
                    },
                    "active_days": {
                      "type": "integer",
                      "description": "Number of active days in the selected timeframe."
                    },
                    "number_of_requests": {
                      "type": "integer",
                      "description": "Total requests made by this user."
                    },
                    "total_requests": {
                      "type": "integer",
                      "description": "Alias of `number_of_requests` for backward compatibility."
                    },
                    "total_tokens": {
                      "type": "integer",
                      "description": "Total tokens used by this user."
                    },
                    "tokens": {
                      "type": "integer",
                      "description": "Alias of `total_tokens` for backward compatibility."
                    },
                    "total_cost": {
                      "type": "number",
                      "description": "Total cost in USD."
                    },
                    "cost": {
                      "type": "number",
                      "description": "Alias of `total_cost` for backward compatibility."
                    },
                    "average_latency": {
                      "type": "number",
                      "nullable": true,
                      "description": "Average latency in seconds."
                    },
                    "average_ttft": {
                      "type": "number",
                      "nullable": true,
                      "description": "Average time to first token in seconds."
                    },
                    "average_monthly_cost": {
                      "type": "number",
                      "description": "Estimated average monthly cost based on observed activity."
                    },
                    "period_budget": {
                      "type": "number",
                      "nullable": true,
                      "description": "Current period budget in USD, when configured."
                    },
                    "budget_duration": {
                      "type": "string",
                      "enum": [
                        "daily",
                        "weekly",
                        "monthly"
                      ],
                      "description": "Budget renewal period."
                    },
                    "total_budget": {
                      "type": "number",
                      "nullable": true,
                      "description": "Lifetime spending budget in USD, when configured."
                    }
                  }
                },
                "description": "Users for the current page."
              }
            },
            "required": [
              "count",
              "results"
            ]
          },
          "example": {
            "count": 51,
            "next": "https://api.respan.ai/api/users/list/?page=2",
            "previous": null,
            "results": [
              {
                "id": "user_123prod8264a3f4-40c7-476a-97d1-96908127ea21",
                "customer_identifier": "user_123",
                "unique_organization_id": "8264a3f4-40c7-476a-97d1-96908127ea21",
                "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_requests": 15420,
                "total_tokens": 170000,
                "tokens": 170000,
                "total_cost": 523.45,
                "cost": 523.45,
                "average_latency": 1.23,
                "average_ttft": 0.45,
                "average_monthly_cost": 6.98,
                "period_budget": 100,
                "budget_duration": "monthly",
                "total_budget": 1000
              }
            ]
          }
        }
      }
    },
    "400": {
      "description": "Bad Request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Invalid filters payload."
              }
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "413": {
      "description": "The query exceeded a memory or execution-time resource limit.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "This query is too large to run — it exceeded a per-query resource limit. Narrow the time range or add filters, then try again."
          }
        }
      }
    },
    "429": {
      "description": "Rate Limited",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Request was throttled. Expected available in 1 second."
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "x-fern-pagination": {
    "offset": "$request.page",
    "results": "$response.results"
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "schemas": {
    "FilterValue": {
      "type": "object",
      "description": "A filter condition with an operator and value.",
      "required": [
        "value"
      ],
      "properties": {
        "operator": {
          "type": "string",
          "description": "Comparison operator. An empty string means equals.",
          "enum": [
            "",
            "not",
            "in",
            "not_in",
            "lt",
            "lte",
            "gt",
            "gte",
            "contains",
            "not_contains",
            "icontains",
            "startswith",
            "not_startswith",
            "endswith",
            "not_endswith",
            "empty",
            "not_empty"
          ],
          "default": "",
          "example": "gte"
        },
        "value": {
          "type": "array",
          "description": "Value(s) to filter by.",
          "items": {},
          "example": [
            0.01
          ]
        }
      }
    },
    "Filters": {
      "type": "object",
      "description": "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.\n\n**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 `[\"\"]`.\n\nThe fields you can filter on depend on the endpoint; `metadata__<key>` filters custom metadata where the endpoint supports it.",
      "properties": {
        "status": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "status_code": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "unique_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "customer_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "thread_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "custom_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "group_identifier": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "prompt_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "trace_unique_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "span_parent_id": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "is_root_span": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "span_workflow_name": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "span_name": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "model": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "log_type": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "stream": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "has_tool_calls": {
          "$ref": "#/components/schemas/FilterValue",
          "description": "Whether the span made tool calls."
        },
        "cache_bit": {
          "$ref": "#/components/schemas/FilterValue",
          "description": "Whether the response was served from the Respan cache."
        },
        "cache_key": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "prompt_tokens": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "completion_tokens": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "total_tokens": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "cost": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "latency": {
          "$ref": "#/components/schemas/FilterValue"
        },
        "positive_feedback": {
          "$ref": "#/components/schemas/FilterValue"
        }
      },
      "example": {
        "customer_identifier": {
          "operator": "",
          "value": [
            "alex@acme.dev"
          ]
        }
      },
      "additionalProperties": {
        "$ref": "#/components/schemas/FilterValue"
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}