> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helicone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HQL (Helicone Query Language)

> Query your Helicone analytics data directly using SQL with row-level security and built-in limits

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.
</Note>

## 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)

```sql theme={null}
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)

```sql theme={null}
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)

```sql theme={null}
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

```sql theme={null}
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)

```sql theme={null}
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:

```bash theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

#### Execute a Query

**Endpoint:** `POST https://api.helicone.ai/v1/helicone-sql/execute`

```bash theme={null}
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:**

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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](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:

  ```sql theme={null}
  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
  ```
</Warning>

### API Limits

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

## Related

<CardGroup cols={2}>
  <Card title="Custom Properties" icon="tag" href="/features/advanced-usage/custom-properties">
    Enrich requests to make querying easier and more powerful
  </Card>

  <Card title="Reports" icon="chart-bar" href="/features/reports">
    Build saved charts on top of your data
  </Card>

  <Card title="Sessions" icon="link" href="/features/sessions">
    Analyze multi‑turn conversations with session identifiers
  </Card>

  <Card title="Datasets" icon="database" href="/features/datasets">
    Export curated data for fine‑tuning and evaluation
  </Card>
</CardGroup>