Skip to main content
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 REST API

The HQL REST API allows you to execute SQL queries programmatically. All endpoints require authentication via API key.

​
Authentication

Include your API key in the Authorization header: 
Authorization: Bearer <YOUR_API_KEY>

​
Execute a Query

Endpoint: POST https://api.helicone.ai/v1/helicone-sql/execute 
curl -X POST "https://api.helicone.ai/v1/helicone-sql/execute" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT request_model, COUNT(*) as count FROM request_response_rmt WHERE request_created_at > now() - INTERVAL 7 DAY GROUP BY request_model ORDER BY count DESC LIMIT 10"
  }'
Response: 
{
  "data": {
    "rows": [
      {"request_model": "gpt-4o", "count": 1500},
      {"request_model": "claude-3-opus", "count": 800}
    ],
    "elapsedMilliseconds": 124,
    "size": 2048,
    "rowCount": 2
  }
}

​
Get Schema

Endpoint: GET https://api.helicone.ai/v1/helicone-sql/schema Returns available tables and columns for querying. 
curl -X GET "https://api.helicone.ai/v1/helicone-sql/schema" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

​
Download Results as CSV

Endpoint: POST https://api.helicone.ai/v1/helicone-sql/download Executes a query and returns a signed URL to download the results as CSV. 
curl -X POST "https://api.helicone.ai/v1/helicone-sql/download" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM request_response_rmt WHERE request_created_at > now() - INTERVAL 1 DAY LIMIT 1000"
  }'

​
Saved Queries

You can also manage saved queries programmatically:
  • GET /v1/helicone-sql/saved-queries - List all saved queries
  • POST /v1/helicone-sql/saved-query - Create a new saved query
  • GET /v1/helicone-sql/saved-query/{queryId} - Get a specific saved query
  • PUT /v1/helicone-sql/saved-query/{queryId} - Update a saved query
  • DELETE /v1/helicone-sql/saved-query/{queryId} - Delete a saved query
Interactive API documentation: https://api.helicone.ai/docs/#/HeliconeSql
Cost Values Are Stored as IntegersCost values in ClickHouse are stored multiplied by 1,000,000,000 (one billion) for precision. When querying costs via the API, divide by this multiplier to get the actual USD value:
SELECT
  request_model,
  sum(cost) / 1000000000 AS total_cost_usd
FROM request_response_rmt
WHERE request_created_at > now() - INTERVAL 7 DAY
GROUP BY request_model

​
API Limits

  • Query limit: 300,000 rows maximum per query
  • Timeout: 30 seconds per query
  • Rate limits: 100 queries/min, 10 CSV downloads/min

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