Query User Metrics

Search and filter through user-specific metrics

1 min read

post/v1/user/metrics/query

Request example

curl --request POST \
  --url https://api.helicone.ai/v1/user/metrics/query \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "request_response_rmt": {
      "country_code": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "latency": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "cost": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "provider": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "time_to_first_token": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "status": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "request_created_at": {
        "equals": "2026-08-10T12:00:00Z",
        "gte": "2026-08-10T12:00:00Z",
        "lte": "2026-08-10T12:00:00Z",
        "lt": "2026-08-10T12:00:00Z",
        "gt": "2026-08-10T12:00:00Z"
      },
      "response_created_at": {
        "equals": "2026-08-10T12:00:00Z",
        "gte": "2026-08-10T12:00:00Z",
        "lte": "2026-08-10T12:00:00Z",
        "lt": "2026-08-10T12:00:00Z",
        "gt": "2026-08-10T12:00:00Z"
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "organization_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "node_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "job_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "threat": {
        "equals": true
      },
      "request_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "completion_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "prompt_cache_read_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "prompt_cache_write_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "total_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "target_url": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "property_key": {
        "equals": "<string>"
      },
      "properties": {},
      "search_properties": {},
      "scores": {},
      "scores_column": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_body": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "response_body": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "cache_enabled": {
        "equals": true
      },
      "cache_reference_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "cached": {
        "equals": true
      },
      "assets": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "helicone-score-feedback": {
        "equals": true
      },
      "prompt_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_version": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_referrer": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "is_passthrough_billing": {
        "equals": true
      }
    },
    "users_view": {
      "user_user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "user_active_for": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "user_first_active": {
        "equals": "2026-08-10T12:00:00Z",
        "gte": "2026-08-10T12:00:00Z",
        "lte": "2026-08-10T12:00:00Z",
        "lt": "2026-08-10T12:00:00Z",
        "gt": "2026-08-10T12:00:00Z"
      },
      "user_last_active": {
        "equals": "2026-08-10T12:00:00Z",
        "gte": "2026-08-10T12:00:00Z",
        "lte": "2026-08-10T12:00:00Z",
        "lt": "2026-08-10T12:00:00Z",
        "gt": "2026-08-10T12:00:00Z"
      },
      "user_total_requests": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "user_average_requests_per_day_active": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "user_average_tokens_per_request": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "user_total_completion_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "user_total_prompt_tokens": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      },
      "user_cost": {
        "not-equals": 1,
        "equals": 1,
        "gte": 1,
        "lte": 1,
        "lt": 1,
        "gt": 1
      }
    }
  },
  "offset": 1,
  "limit": 1,
  "timeFilter": {
    "endTimeUnixSeconds": 1,
    "startTimeUnixSeconds": 1
  },
  "timeZoneDifferenceMinutes": 1,
  "sort": {
    "id": "asc",
    "user_id": "asc",
    "active_for": "asc",
    "first_active": "asc",
    "last_active": "asc",
    "total_requests": "asc",
    "average_requests_per_day_active": "asc",
    "average_tokens_per_request": "asc",
    "total_prompt_tokens": "asc",
    "total_completion_tokens": "asc",
    "cost": "asc",
    "rate_limited_count": "asc"
  }
}'

Response

{
  "data": {
    "hasUsers": true,
    "count": 1,
    "users": [
      {
        "id": "<string>",
        "user_id": "<string>",
        "active_for": 1,
        "first_active": "<string>",
        "last_active": "<string>",
        "total_requests": 1,
        "average_requests_per_day_active": 1,
        "average_tokens_per_request": 1,
        "total_completion_tokens": 1,
        "total_prompt_tokens": 1,
        "cost": 1
      }
    ]
  },
  "error": null
}

post/v1/user/metrics/query

Warning

For users in the European Union: Please use eu.api.helicone.ai instead of api.helicone.ai.

Authorization

Authorizationstringheaderrequired#

Bearer token authentication. Format: 'Bearer YOUR_API_KEY'

Body

application/json

filterobject · enum<string>required#

Show child attributes

Any of

request_response_rmtobject#

Make all properties in T optional

Show child attributes

country_codeobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

latencyobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

costobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

providerobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

time_to_first_tokenobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

statusobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

request_created_atobject#

Make all properties in T optional

Show child attributes

equalsstring#

gtestring#

ltestring#

ltstring#

gtstring#

response_created_atobject#

Make all properties in T optional

Show child attributes

equalsstring#

gtestring#

ltestring#

ltstring#

gtstring#

modelobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

user_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

organization_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

node_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

job_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

threatobject#

Make all properties in T optional

Show child attributes

equalsboolean#

request_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

prompt_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

completion_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

prompt_cache_read_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

prompt_cache_write_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

total_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

target_urlobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

property_keyobject#

Show child attributes

equalsstringrequired#

propertiesobject#

Show child attributes

{key}object#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

search_propertiesobject#

Show child attributes

{key}object#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

scoresobject#

Show child attributes

{key}object#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

scores_columnobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

request_bodyobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

response_bodyobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

cache_enabledobject#

Make all properties in T optional

Show child attributes

equalsboolean#

cache_reference_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

cachedobject#

Make all properties in T optional

Show child attributes

equalsboolean#

assetsobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

helicone-score-feedbackobject#

Make all properties in T optional

Show child attributes

equalsboolean#

prompt_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

prompt_versionobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

request_referrerobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

is_passthrough_billingobject#

Make all properties in T optional

Show child attributes

equalsboolean#

users_viewobject#

Make all properties in T optional

Show child attributes

user_user_idobject#

Make all properties in T optional

Show child attributes

not-equalsstring#

equalsstring#

likestring#

ilikestring#

containsstring#

not-containsstring#

user_active_forobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

user_first_activeobject#

Make all properties in T optional

Show child attributes

equalsstring#

gtestring#

ltestring#

ltstring#

gtstring#

user_last_activeobject#

Make all properties in T optional

Show child attributes

equalsstring#

gtestring#

ltestring#

ltstring#

gtstring#

user_total_requestsobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

user_average_requests_per_day_activeobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

user_average_tokens_per_requestobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

user_total_completion_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

user_total_prompt_tokensobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

user_costobject#

Make all properties in T optional

Show child attributes

not-equalsnumber#

equalsnumber#

gtenumber#

ltenumber#

ltnumber#

gtnumber#

rightUserFilterNoderequired#

circular

operatorenum<string>required#

Options:orand

leftUserFilterNoderequired#

circular

offsetnumberrequired#

limitnumberrequired#

timeFilterobject#

Show child attributes

endTimeUnixSecondsnumberrequired#

startTimeUnixSecondsnumberrequired#

timeZoneDifferenceMinutesnumber#

sortobject#

Show child attributes

idenum<string>#

Options:ascdesc

user_idenum<string>#

Options:ascdesc

active_forenum<string>#

Options:ascdesc

first_activeenum<string>#

Options:ascdesc

last_activeenum<string>#

Options:ascdesc

total_requestsenum<string>#

Options:ascdesc

average_requests_per_day_activeenum<string>#

Options:ascdesc

average_tokens_per_requestenum<string>#

Options:ascdesc

total_prompt_tokensenum<string>#

Options:ascdesc

total_completion_tokensenum<string>#

Options:ascdesc

costenum<string>#

Options:ascdesc

rate_limited_countenum<string>#

Options:ascdesc

Responses

application/json

200

Any of

dataobjectrequired#

Show child attributes

hasUsersbooleanrequired#

countnumberrequired#

usersobject[]required#

Show child attributes

idstringrequired#

user_idstringrequired#

active_fornumberrequired#

first_activestringrequired#

last_activestringrequired#

total_requestsnumberrequired#

average_requests_per_day_activenumberrequired#

average_tokens_per_requestnumberrequired#

total_completion_tokensnumberrequired#

total_prompt_tokensnumberrequired#

costnumberrequired#

errorenum<number>required#

Options:null

dataenum<number>required#

Options:null

errorstringrequired#

Query User Metrics Overview Get User Data