Query Sessions

Retrieve sessions with filtering and pagination

Endpoint

method · string · default: "POST"

POST

endpoint · string

/v1/session/query

Authentication

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

Authorization: Bearer YOUR_API_KEY

Request Body

search · string · required

Search string to filter sessions

timeFilter · object · required

Time range filter for sessions

startTimeUnixMs · number · required

Start time in Unix milliseconds

endTimeUnixMs · number · required

End time in Unix milliseconds

nameEquals · string

Filter by exact session name

timezoneDifference · number · required

Timezone offset in minutes

filter · object · required

Advanced filtering options. Can be “all” for no filter, or a filter tree with request_response_rmt and sessions_request_response_rmt operators

offset · number

Number of records to skip (for pagination)

limit · number

Maximum number of records to return

Response

data · array

Array of session objects

session_id · string

Unique identifier for the session

session_name · string

Name of the session

total_cost · number

Total cost of all requests in the session

total_tokens · number

Total number of tokens used in the session

prompt_tokens · number

Total prompt tokens used

completion_tokens · number

Total completion tokens used

total_requests · number

Number of requests in the session

created_at · string

Session creation timestamp

latest_request_created_at · string

Timestamp of the most recent request

error · string | null

Error message if the request failed, null otherwise

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": "",
    "timeFilter": {
      "startTimeUnixMs": 1704067200000,
      "endTimeUnixMs": 1706745600000
    },
    "timezoneDifference": 0,
    "filter": "all",
    "offset": 0,
    "limit": 10
  }'

Example Response

{
  "data": [
    {
      "session_id": "sess_abc123",
      "session_name": "Customer Support Chat",
      "total_cost": 0.0045,
      "total_tokens": 1500,
      "prompt_tokens": 800,
      "completion_tokens": 700,
      "total_requests": 5,
      "created_at": "2024-01-15T10:30:00Z",
      "latest_request_created_at": "2024-01-15T10:45:00Z"
    }
  ],
  "error": null
}