Querying Telemetry Data

Query your telemetry data using SQL via the Insights API. Insights provides full SQL support over all your stored telemetry.

TIP

Looking for the portal experience? See Insights & Observability for exploring your telemetry visually, or build a custom dashboard with SQL queries and charts.

Endpoint

POST https://insights.nextepoch.cloud/v1/query

Authentication

Include a JWT token from the Identity service in the Authorization header:

Authorization: Bearer <your-jwt-token>

Basic Query

curl -X POST https://insights.nextepoch.cloud/v1/query \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT * FROM logs WHERE level = '\''error'\'' ORDER BY timestamp DESC LIMIT 10"
  }'

Available Tables

Each telemetry type is available as a SQL table. Data is automatically scoped to your organization.

Table	Description
logs	Log entries with level, message, and attributes
metrics	Metric measurements with name, value, and tags
traces	Distributed trace spans
audit	Audit trail events

Example Queries

Error count by service (last 24h)

SELECT
  attributes['service'] as service,
  COUNT(*) as error_count
FROM logs
WHERE level = 'error'
  AND timestamp > NOW() - INTERVAL '24 hours'
GROUP BY service
ORDER BY error_count DESC

Average request duration by endpoint

SELECT
  tags['path'] as endpoint,
  AVG(value) as avg_duration_ms,
  COUNT(*) as request_count
FROM metrics
WHERE name = 'http_request_duration_ms'
  AND timestamp > NOW() - INTERVAL '1 hour'
GROUP BY endpoint
ORDER BY avg_duration_ms DESC

Slow traces

SELECT
  timestamp,
  name,
  duration_ms,
  attributes['service'] as service
FROM traces
WHERE duration_ms > 1000
ORDER BY duration_ms DESC
LIMIT 20

SQL Features

Insights supports standard SQL including:

• WHERE, GROUP BY, ORDER BY, LIMIT
• Aggregate functions: COUNT, SUM, AVG, MIN, MAX
• Time functions: NOW(), date_trunc(), INTERVAL
• JSON attribute access with bracket notation: attributes['key']

Next Steps

• Insights API Reference — Full query endpoint docs
• Sending Data — Ingest more telemetry