Session Metrics

Get aggregated metrics for sessions

Endpoint

method · string · default: "POST"

POST

endpoint · string

/v1/session/metrics/query

Authentication

This endpoint requires API key authentication. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Request Body

nameContains · string · required

Filter sessions by name substring

timezoneDifference · number · required

Timezone offset in minutes

pSize · string

Percentile size for metrics calculation. Options: “p50”, “p75”, “p95”, “p99”, “p99.9”

useInterquartile · boolean

Whether to use interquartile range for outlier detection

timeFilter · object

Time range filter

startTimeUnixMs · number

Start time in Unix milliseconds

endTimeUnixMs · number

End time in Unix milliseconds

filter · object

Advanced filter for sessions

Response

data · object

Session metrics data

averageCost · number

Average cost per session

averageTokens · number

Average tokens per session

averageRequests · number

Average number of requests per session

totalSessions · number

Total number of sessions

totalCost · number

Sum of all session costs

totalTokens · number

Sum of all tokens used

totalRequests · number

Sum of all requests

error · string | null

Error message if the request failed, null otherwise

Example Request

curl -X POST https://api.helicone.ai/v1/session/metrics/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nameContains": "",
    "timezoneDifference": 0,
    "pSize": "p95",
    "timeFilter": {
      "startTimeUnixMs": 1704067200000,
      "endTimeUnixMs": 1706745600000
    }
  }'

Example Response

{
  "data": {
    "averageCost": 0.0042,
    "averageTokens": 1450,
    "averageRequests": 4.5,
    "totalSessions": 150,
    "totalCost": 0.63,
    "totalTokens": 217500,
    "totalRequests": 675
  },
  "error": null
}