list_customers
Retrieve paginated customer lists with sorting by cost, activity, or tokens to identify top users and monitor usage.
Instructions
List customers/users with pagination and sorting.
Retrieves a paginated list of customers who have made API requests through Respan.
QUERY PARAMETERS:
page_size: Number of customers per page (max 50 for MCP, API supports up to 1000)
page: Page number (default 1)
sort_by: Sort field. Prefix with - for descending order. Examples: -total_cost (highest spending first), -number_of_requests (most active first)
environment: Filter by environment ("prod" or "test")
RESPONSE FIELDS:
id: Unique internal identifier
customer_identifier: Your unique identifier for this customer
email: Customer email (if provided)
name: Customer name (if provided)
environment: Environment (prod/test)
first_seen: First activity timestamp
last_active_timeframe: Last activity timestamp
active_days: Number of days with activity
number_of_requests: Total API requests made
total_tokens: Total tokens used
total_cost: Total cost in USD
average_latency: Average response time in seconds
average_ttft: Average time to first token in seconds
Use this to identify top users by cost, most active users, or find specific customers.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_customers"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1) | |
| sort_by | No | Sort field. Prefix with - for descending order. Default: -first_seen | |
| page_size | No | Customers per page (1-50, default 20) | |
| environment | No | Filter by environment: 'prod' or 'test' |