Query Users

Retrieve aggregated user data based on user IDs and time filters

This endpoint retrieves aggregated usage statistics for specific users. Use this to analyze user behavior, track token consumption, and calculate costs per user.

Use Cases

• Analyze individual user behavior
• Track token usage per user
• Calculate per-user costs
• Monitor user activity levels
• Generate user-specific usage reports

Request Body

userIds · string[]

Array of user IDs to query. If not provided, returns data for all users.

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

Response

Returns a Result object containing an array of user statistics.

data · array

Array of user statistics objects

data[].user_id · string

The user identifier

data[].count · number

Total number of requests made by the user

data[].prompt_tokens · number

Total prompt tokens consumed by the user

data[].completion_tokens · number

Total completion tokens generated for the user

data[].cost · number

Total cost in USD for the user’s requests

error · string | null

Error message if the request failed, null otherwise

Example Request

curl --request POST \
  --url https://api.helicone.ai/v1/user/query \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userIds": ["user_123", "user_456"],
    "timeFilter": {
      "startTimeUnixSeconds": 1704067200,
      "endTimeUnixSeconds": 1706745600
    }
  }'

Example Response

{
  "data": [
    {
      "user_id": "user_123",
      "count": 250,
      "prompt_tokens": 15000,
      "completion_tokens": 12000,
      "cost": 2.45
    },
    {
      "user_id": "user_456",
      "count": 180,
      "prompt_tokens": 10500,
      "completion_tokens": 8400,
      "cost": 1.73
    }
  ],
  "error": null
}

Notes

• Results are limited to 100 users per request
• User IDs must match the values passed in the Helicone-User-Id header during request logging
• Costs are calculated based on the model pricing at the time of the request
• If no timeFilter is provided, defaults to all time