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

# Troubleshooting

> Troubleshoot common Unkey Analytics issues including query timeouts, permission errors, missing data, memory limits, and syntax errors.

# Analytics Troubleshooting

## Getting Empty Results?

**Check these common causes:**

### Time Range Issues

* Your workspace might be new with no verification data yet
* Try a shorter time range: `WHERE time >= now() - INTERVAL 1 HOUR`
* Verify your time filters are working: `SELECT MAX(time) as latest FROM key_verifications_v1`

### Filter Problems

* Wrong `key_space_id` - Find your API ID in dashboard settings
* Empty `external_id` values - Filter them out: `WHERE external_id != ''`
* Case sensitivity - Check exact values: `SELECT DISTINCT external_id FROM key_verifications_v1 LIMIT 10`

### Data Availability

* Analytics may have a few minutes delay
* Check recent data: `SELECT COUNT(*) FROM key_verifications_v1 WHERE time >= now() - INTERVAL 1 HOUR`

## Queries Timing Out?

**Try these optimizations:**

### Use Aggregated Tables

```sql theme={"theme":"kanagawa-wave"}
-- Instead of raw table for long ranges:
-- Slow for 7+ days
SELECT COUNT(*) FROM key_verifications_v1 WHERE time >= now() - INTERVAL 7 DAY

-- Fast for 7+ days
SELECT SUM(count) FROM key_verifications_per_day_v1 WHERE time >= now() - INTERVAL 7 DAY
```

### Add Time Filters First

```sql theme={"theme":"kanagawa-wave"}
-- Always filter by time early (uses indexes)
WHERE time >= now() - INTERVAL 7 DAY
  AND external_id = 'user_123'  -- Additional filters after time
```

### Limit Result Size

```sql theme={"theme":"kanagawa-wave"}
-- Prevent large result sets
SELECT external_id, SUM(count) as usage
FROM key_verifications_per_day_v1
WHERE time >= now() - INTERVAL 30 DAY
GROUP BY external_id
ORDER BY usage DESC
LIMIT 100  -- Add LIMIT for large datasets
```

## API Errors?

**Common fixes:**

### Missing Property 'query'

```json theme={"theme":"kanagawa-wave"}
// Wrong field name
{"sql": "SELECT COUNT(*) FROM key_verifications_v1"}

// Correct field name
{"query": "SELECT COUNT(*) FROM key_verifications_v1"}
```

See `invalid_input` error for API request format issues.

### Permission Denied

* Ensure your root key has `api.*.read_analytics` or `api.<api_id>.read_analytics`
* Check key is not expired or revoked
* Verify workspace ID matches your key's permissions
  See the `forbidden` error for permission issues.

### Invalid Function Error

* Check [Query Restrictions](/platform/analytics/query-restrictions#function-allow-list) for allowed functions
* Some ClickHouse functions are blocked for security
* Use alternative approaches from [Quick Reference](/platform/analytics/quick-reference)
* See `invalid_analytics_function` error for details

### Invalid Table Error

* Only analytics tables are accessible (no `system.*` or `information_schema.*`)
* Use table names from [Schema Reference](/platform/analytics/schema-reference)
* See `invalid_analytics_table` error for details

### Query Not Supported

* Only SELECT queries are allowed in analytics
* INSERT, UPDATE, DELETE, etc. are blocked
* See `invalid_analytics_query_type` error for details

## Performance Problems?

**Optimization tips:**

### Choose Right Table

* `< 1 hour`: `key_verifications_v1` (raw)
* `< 24 hours`: `key_verifications_per_minute_v1`
* `< 30 days`: `key_verifications_per_hour_v1`
* `< 1 year`: `key_verifications_per_day_v1`
* `> 1 year`: `key_verifications_per_month_v1`

### Filter Before Grouping

```sql theme={"theme":"kanagawa-wave"}
-- Less efficient
SELECT external_id, SUM(count) as usage
FROM key_verifications_per_day_v1
GROUP BY external_id
HAVING SUM(count) > 1000

-- More efficient
SELECT external_id, SUM(count) as usage
FROM key_verifications_per_day_v1
WHERE time >= now() - INTERVAL 30 DAY  -- Filter first
GROUP BY external_id
HAVING SUM(count) > 1000
```

### Avoid SELECT \*

* Only select columns you need
* Reduces memory usage and network transfer

<Note>
  For complete error reference, see the Error Documentation in the sidebar. If
  you continue having issues, contact us at
  [support@unkey.com](mailto:support@unkey.com) with your query and error
  details.
</Note>