Query Session Metrics

Retrieve detailed performance metrics and statistical distributions for sessions

Overview

The Session Metrics endpoint provides statistical analysis of session performance, including percentile distributions for session count, duration, and cost. This is useful for understanding typical session patterns and identifying outliers.

Request Parameters

nameContains · string

Filter sessions by session name (partial match)

timezoneDifference · number · required

Timezone offset in minutes from UTC

pSize · string · default: "p75"

Percentile size for histogram calculations

Options: p50, p75, p95, p99, p99.9

useInterquartile · boolean · default: "false"

Use interquartile range for outlier detection

timeFilter · object

Time range filter for the metrics query

startTimeUnixMs · number

Start time in Unix milliseconds

endTimeUnixMs · number

End time in Unix milliseconds

filter · object

Advanced filter node for complex queries

Response Fields

data · object

Session metrics data

session_count · array

Histogram data for request counts per session

bucket · number

Request count bucket

frequency · number

Number of sessions in this bucket

session_duration · array

Histogram data for session duration in seconds

bucket · number

Duration bucket (in seconds)

frequency · number

Number of sessions in this bucket

session_cost · array

Histogram data for session costs

bucket · number

Cost bucket (in USD)

frequency · number

Number of sessions in this bucket

average · object

Average metrics across all sessions

session_count · array

Average request count per session over time

time · string

Timestamp

value · number

Average count

session_duration · array

Average session duration over time

time · string

Timestamp

value · number

Average duration in seconds

session_cost · array

Average session cost over time

time · string

Timestamp

value · number

Average cost in USD

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": "production",
    "timezoneDifference": 0,
    "pSize": "p95",
    "useInterquartile": false,
    "timeFilter": {
      "startTimeUnixMs": 1704067200000,
      "endTimeUnixMs": 1704153600000
    },
    "filter": "all"
  }'

Example Response

{
  "data": {
    "session_count": [
      { "bucket": 1, "frequency": 45 },
      { "bucket": 5, "frequency": 120 },
      { "bucket": 10, "frequency": 80 },
      { "bucket": 20, "frequency": 35 }
    ],
    "session_duration": [
      { "bucket": 60, "frequency": 90 },
      { "bucket": 300, "frequency": 150 },
      { "bucket": 600, "frequency": 40 }
    ],
    "session_cost": [
      { "bucket": 0.001, "frequency": 100 },
      { "bucket": 0.01, "frequency": 120 },
      { "bucket": 0.1, "frequency": 60 }
    ],
    "average": {
      "session_count": [
        { "time": "2024-01-01T00:00:00Z", "value": 7.5 },
        { "time": "2024-01-01T01:00:00Z", "value": 8.2 }
      ],
      "session_duration": [
        { "time": "2024-01-01T00:00:00Z", "value": 245.5 },
        { "time": "2024-01-01T01:00:00Z", "value": 267.3 }
      ],
      "session_cost": [
        { "time": "2024-01-01T00:00:00Z", "value": 0.0085 },
        { "time": "2024-01-01T01:00:00Z", "value": 0.0092 }
      ]
    }
  },
  "error": null
}

Understanding Percentiles

The pSize parameter controls which percentile to use for histogram bucketing:

• p50 (median): Half of sessions fall below this value
• p75: 75% of sessions fall below this value
• p95: 95% of sessions fall below this value - useful for SLA monitoring
• p99: 99% of sessions fall below this value - helps identify outliers
• p99.9: Captures extreme outliers

Use Cases

• Performance monitoring: Track session duration trends over time
• Cost analysis: Understand cost distribution across sessions
• Capacity planning: Identify typical session patterns for scaling
• Anomaly detection: Use high percentiles (p95, p99) to spot unusual behavior
• SLA compliance: Monitor percentile-based service level objectives

Interquartile Range

When useInterquartile is set to true, the metrics use the interquartile range (IQR) method for outlier detection. This provides a more robust statistical view by focusing on the middle 50% of data and reducing the impact of extreme outliers.