HQL (Helicone Query Language) - Helicone OSS LLM Observability

Helicone Query Language (HQL) lets you query your Helicone analytics data directly using SQL.

Note

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_costFROM request_response_rmtWHERE request_created_at > now() - INTERVAL 7 DAYORDER BY provider_total_cost DESCLIMIT 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_rateFROM request_response_rmtWHERE 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 dauFROM request_response_rmtWHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 14 DAYGROUP BY dayORDER BY day

Session analysis using custom properties#

SELECT   properties['Helicone-Session-Id'] AS session_id,  COUNT(*) AS requests,  sum(cost) AS total_costFROM request_response_rmtWHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 7 DAY  AND properties['Helicone-Session-Id'] IS NOT NULLGROUP BY session_idORDER BY total_cost DESCLIMIT 100

Cost by model (last 30 days)#

SELECT   request_model,  sum(cost) AS total_cost,  COUNT() AS request_countFROM request_response_rmtWHERE request_created_at >= toDateTime64(now(), 3) - INTERVAL 30 DAYGROUP BY request_modelORDER BY total_cost DESC

How to use HQL#

In the Dashboard#

Go to HQL in the sidebar
Browse tables and columns in the left panel
Write your SQL in the editor
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

Warning

Cost Values Are Stored as Integers

Cost 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_usdFROM request_response_rmtWHERE request_created_at > now() - INTERVAL 7 DAYGROUP 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

What you can query#

Examples#

Top costly requests (last 7 days)#

Error rate (last 24 hours)#

Active users by day (last 14 days)#

Session analysis using custom properties#

Cost by model (last 30 days)#

How to use HQL#

In the Dashboard#

Via REST API#

Authentication#

Execute a Query#

Get Schema#

Download Results as CSV#

Saved Queries#

API Limits#

Related#