Helicone Query Language (HQL) lets you query your Helicone analytics data directly using SQL.
HQL is currently available to selected workspaces. If you don’t see the HQL page in your dashboard, click “Request Access” from the HQL screen or contact support.

​
What you can query

  • request_created_at: timestamp of the request
  • request_model: model name used (e.g. gpt-4o)
  • status: HTTP status code
  • user_id: your application user identifier (if provided)
  • cost / provider_total_cost: cost metrics
  • prompt_tokens, completion_tokens, total_tokens: token usage
  • properties: custom properties map (e.g. properties['Helicone-Session-Id'])

​
Examples

​
Top costly requests (last 7 days)

SELECT 
  request_created_at,
  request_model,
  response_body,
  provider_total_cost
FROM request_response_rmt
WHERE request_created_at > now() - INTERVAL 7 DAY
ORDER BY provider_total_cost DESC
LIMIT 100

​
Error rate (last 24 hours)

SELECT 
  COUNTIf(status BETWEEN 400 AND 599) AS error_count,
  COUNT() AS total_requests,
  ROUND(error_count / total_requests, 4) AS error_rate
FROM request_response_rmt
WHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 24 HOUR

​
Active users by day (last 14 days)

SELECT 
  toDate(request_created_at) AS day,
  COUNT(DISTINCT user_id) AS dau
FROM request_response_rmt
WHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 14 DAY
GROUP BY day
ORDER BY day

​
Session analysis using custom properties

SELECT 
  properties['Helicone-Session-Id'] AS session_id,
  COUNT(*) AS requests,
  sum(cost) AS total_cost
FROM request_response_rmt
WHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 7 DAY
  AND properties['Helicone-Session-Id'] IS NOT NULL
GROUP BY session_id
ORDER BY total_cost DESC
LIMIT 100

​
Cost by model (last 30 days)

SELECT 
  request_model,
  sum(cost) AS total_cost,
  COUNT() AS request_count
FROM request_response_rmt
WHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 30 DAY
GROUP BY request_model
ORDER BY total_cost DESC

​
How to use HQL

​
In the Dashboard

  1. Go to HQL in the sidebar
  2. Browse tables and columns in the left panel
  3. Write your SQL in the editor
  4. Press Cmd/Ctrl+Enter to run; Cmd/Ctrl+S to save as a query
Saved queries can be revisited and shared within your organization.

​
Via API

HQL endpoints are namespaced under /v1/helicone-sql and require an authenticated request scoped to your organization. 
curl -X POST "https://api.helicone.ai/v1/helicone-sql/execute" \
  -H "Authorization: Bearer $HELICONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT request_model, COUNT() AS c FROM request_response_rmt GROUP BY request_model ORDER BY c DESC LIMIT 50"
  }'
Download large result sets as CSV: 
curl -X POST "https://api.helicone.ai/v1/helicone-sql/download" \
  -H "Authorization: Bearer $HELICONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM request_response_rmt WHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 7 DAY"
  }'

Custom Properties

Enrich requests to make querying easier and more powerful

Reports

Build saved charts on top of your data

Sessions

Analyze multi‑turn conversations with session identifiers

Datasets

Export curated data for fine‑tuning and evaluation