Skip to main content

​
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
}

Build docs developers (and LLMs) love

Get started for freeTalk to us