Query Sessions

Search and filter through session data with advanced filtering options

Overview

The Query Sessions endpoint allows you to retrieve session data with powerful filtering capabilities. Sessions group related requests together, enabling you to track conversations, multi-step workflows, or any sequence of API calls.

Request Parameters

search · string

Search term to filter sessions by session ID or session name (case-insensitive)

timeFilter · object · required

Time range filter for the query

startTimeUnixMs · number · required

Start time in Unix milliseconds

endTimeUnixMs · number · required

End time in Unix milliseconds

nameEquals · string

Filter sessions by exact session name match

timezoneDifference · number · required

Timezone offset in minutes from UTC

filter · object · required

Advanced filter node for complex queries. Can be a filter leaf, filter branch, or “all” to match all sessions.

offset · number · default: "0"

Number of sessions to skip for pagination

limit · number · default: "50"

Maximum number of sessions to return (max: 1000)

Response Fields

data · array

Array of session objects

session_id · string

Unique identifier for the session

session_name · string

Human-readable name for the session

created_at · string

ISO 8601 timestamp of when the session was created

latest_request_created_at · string

ISO 8601 timestamp of the most recent request in this session

total_cost · number

Total cost of all requests in the session (in USD)

total_requests · number

Number of requests in the session

prompt_tokens · number

Total prompt tokens used across all requests

completion_tokens · number

Total completion tokens generated across all requests

total_tokens · number

Sum of prompt and completion tokens

avg_latency · number

Average latency across all requests in milliseconds

user_ids · array

Array of unique user IDs associated with this session

Example Request

curl -X POST https://api.helicone.ai/v1/session/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "customer-support",
    "timeFilter": {
      "startTimeUnixMs": 1704067200000,
      "endTimeUnixMs": 1704153600000
    },
    "timezoneDifference": 0,
    "filter": "all",
    "offset": 0,
    "limit": 50
  }'

Example Response

{
  "data": [
    {
      "session_id": "sess_abc123",
      "session_name": "customer-support-chat",
      "created_at": "2024-01-01T12:00:00Z",
      "latest_request_created_at": "2024-01-01T12:15:00Z",
      "total_cost": 0.0042,
      "total_requests": 8,
      "prompt_tokens": 1250,
      "completion_tokens": 890,
      "total_tokens": 2140,
      "avg_latency": 450.5,
      "user_ids": ["user_123"]
    }
  ],
  "error": null
}

Filtering Sessions

You can use the filter parameter to create complex queries:

Filter by session properties

{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "Helicone-Session-Name": {
          "equals": "production-chat"
        }
      }
    }
  }
}

Combine multiple filters

{
  "filter": {
    "left": {
      "request_response_rmt": {
        "properties": {
          "Helicone-Session-Name": {
            "contains": "support"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "cost": {
          "gt": 0.001
        }
      }
    }
  }
}

Use Cases

• Track conversations: Monitor multi-turn chat sessions
• Analyze workflows: Group related API calls together
• Cost monitoring: Track spending per session
• Performance analysis: Measure session duration and latency
• User analytics: Understand user behavior across sessions