Warning
For users in the European Union: Please use eu.api.helicone.ai instead of
api.helicone.ai.
Query Sessions
Search and filter through session data
1 min read
post/v1/session/query
Request example
curl --request POST \
--url https://api.helicone.ai/v1/session/query \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"search": "<string>",
"timeFilter": {
"endTimeUnixMs": 1,
"startTimeUnixMs": 1
},
"nameEquals": "<string>",
"timezoneDifference": 1,
"filter": {
"request_response_rmt": {
"country_code": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"latency": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"cost": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"provider": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"time_to_first_token": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"status": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"request_created_at": {
"equals": "2026-08-10T12:00:00Z",
"gte": "2026-08-10T12:00:00Z",
"lte": "2026-08-10T12:00:00Z",
"lt": "2026-08-10T12:00:00Z",
"gt": "2026-08-10T12:00:00Z"
},
"response_created_at": {
"equals": "2026-08-10T12:00:00Z",
"gte": "2026-08-10T12:00:00Z",
"lte": "2026-08-10T12:00:00Z",
"lt": "2026-08-10T12:00:00Z",
"gt": "2026-08-10T12:00:00Z"
},
"model": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"user_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"organization_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"node_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"job_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"threat": {
"equals": true
},
"request_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"prompt_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"completion_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"prompt_cache_read_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"prompt_cache_write_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"total_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"target_url": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"property_key": {
"equals": "<string>"
},
"properties": {},
"search_properties": {},
"scores": {},
"scores_column": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"request_body": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"response_body": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"cache_enabled": {
"equals": true
},
"cache_reference_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"cached": {
"equals": true
},
"assets": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"helicone-score-feedback": {
"equals": true
},
"prompt_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"prompt_version": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"request_referrer": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"is_passthrough_billing": {
"equals": true
}
},
"sessions_request_response_rmt": {
"session_session_id": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"session_session_name": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
},
"session_total_cost": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"session_total_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"session_prompt_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"session_completion_tokens": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"session_total_requests": {
"not-equals": 1,
"equals": 1,
"gte": 1,
"lte": 1,
"lt": 1,
"gt": 1
},
"session_created_at": {
"equals": "2026-08-10T12:00:00Z",
"gte": "2026-08-10T12:00:00Z",
"lte": "2026-08-10T12:00:00Z",
"lt": "2026-08-10T12:00:00Z",
"gt": "2026-08-10T12:00:00Z"
},
"session_latest_request_created_at": {
"equals": "2026-08-10T12:00:00Z",
"gte": "2026-08-10T12:00:00Z",
"lte": "2026-08-10T12:00:00Z",
"lt": "2026-08-10T12:00:00Z",
"gt": "2026-08-10T12:00:00Z"
},
"session_tag": {
"not-equals": "<string>",
"equals": "<string>",
"like": "<string>",
"ilike": "<string>",
"contains": "<string>",
"not-contains": "<string>"
}
}
},
"offset": 1,
"limit": 1
}'Response
{
"data": [
{
"created_at": "<string>",
"latest_request_created_at": "<string>",
"session_id": "<string>",
"session_name": "<string>",
"total_cost": 1,
"total_requests": 1,
"prompt_tokens": 1,
"completion_tokens": 1,
"total_tokens": 1,
"avg_latency": 1,
"user_ids": [
"<string>"
]
}
],
"error": null
}post/v1/session/query
Authorization
Bearer token authentication. Format: 'Bearer YOUR_API_KEY'
Body
application/jsonResponses
application/json
200
Ok