Query User Metrics

Retrieve detailed user metrics with advanced filtering and pagination

This endpoint provides comprehensive user metrics including activity patterns, token usage, and cost analytics. Use advanced filtering to segment users and pagination to handle large result sets.

Use Cases

• Generate detailed user analytics reports
• Identify most active users
• Track user engagement over time
• Calculate average requests per active day
• Monitor per-user costs and token consumption

Request Body

filter · UserFilterNode · required

Filter criteria for users. Can be “all” to retrieve all users, or a filter tree structure to specify conditions.

offset · number · required

Number of records to skip for pagination (0-based)

limit · number · required

Maximum number of records to return. Cannot exceed 1000.

timeFilter · object

Time range for filtering data

timeFilter.startTimeUnixSeconds · number · required

Start time as Unix timestamp in seconds

timeFilter.endTimeUnixSeconds · number · required

End time as Unix timestamp in seconds

timeZoneDifferenceMinutes · number

Time zone difference in minutes from UTC for time-based calculations

sort · SortLeafUsers

Sorting configuration for the results

Response

Returns a Result object containing user metrics data.

data · object

User metrics response object

data.users · UserMetricsResult[]

Array of user metrics objects

data.users[].id · string

Internal user record ID

data.users[].user_id · string

The user identifier

data.users[].active_for · number

Number of days the user has been active

data.users[].first_active · string

ISO 8601 timestamp of first activity

data.users[].last_active · string

ISO 8601 timestamp of last activity

data.users[].total_requests · number

Total number of requests made by the user

data.users[].average_requests_per_day_active · number

Average number of requests per active day

data.users[].average_tokens_per_request · number

Average total tokens (prompt + completion) per request

data.users[].total_completion_tokens · number

Total completion tokens generated

data.users[].total_prompt_tokens · number

Total prompt tokens consumed

data.users[].cost · number

Total cost in USD

data.count · number

Total number of users matching the filter (for pagination)

data.hasUsers · boolean

Whether any users were found

error · string | null

Error message if the request failed, null otherwise

Example Request

curl --request POST \
  --url https://api.helicone.ai/v1/user/metrics/query \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": "all",
    "offset": 0,
    "limit": 50,
    "timeFilter": {
      "startTimeUnixSeconds": 1704067200,
      "endTimeUnixSeconds": 1706745600
    }
  }'

Example Response

{
  "data": {
    "users": [
      {
        "id": "rec_123",
        "user_id": "user_123",
        "active_for": 30,
        "first_active": "2024-01-01T00:00:00Z",
        "last_active": "2024-01-30T23:59:59Z",
        "total_requests": 450,
        "average_requests_per_day_active": 15.0,
        "average_tokens_per_request": 850.5,
        "total_completion_tokens": 192000,
        "total_prompt_tokens": 191250,
        "cost": 12.45
      }
    ],
    "count": 120,
    "hasUsers": true
  },
  "error": null
}

Error Response

{
  "data": null,
  "error": "Limit cannot be greater than 1000"
}

Notes

• Maximum limit is 1000 users per request
• Use offset and limit for pagination through large result sets
• Active days are calculated based on days with at least one request
• Costs are calculated based on model pricing at the time of each request