Exporting Query Results

Use the synchronous Query API for compact interactive results. Use an asynchronous query when the scan or result is too large to hold an HTTP request open, or when a downstream system needs JSON or Parquet.

Shape the export first

Export only the columns and time range the consumer needs. A bounded, explicit query is easier to review and less likely to expose unrelated fields:

SELECT
  date_trunc('day', timestamp_utc) AS day,
  feature,
  SUM(estimated_cost_usd) AS cost_usd
FROM llm_requests
WHERE timestamp_utc >= now() - INTERVAL '30 days'
GROUP BY date_trunc('day', timestamp_utc), feature
ORDER BY day, feature;

Prefer Parquet when a data tool will scan a large typed result. Prefer JSON when a script or workflow needs a smaller result directly.

Start an asynchronous query

curl -X POST https://api.telemetry.sh/query/async \
  -H "Authorization: Bearer $TELEMETRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM api_requests WHERE timestamp_utc >= now() - INTERVAL '\''24 hours'\''",
    "format": "parquet"
  }'

The accepted response contains a job ID and status URL. Poll the status URL with the same read-capable API key until the job is complete or terminally failed. Back off between polls rather than running a tight loop.

When complete, download the result from the returned URL before it expires. Treat download URLs and exported files according to the sensitivity of the selected columns.

Make exports reproducible

Store the reviewed SQL, export format, schedule, owner, and destination with the automation. Use a fixed closed time window for scheduled reports so retries do not silently export a different period.

For incremental delivery, define a watermark and overlap policy. Late-arriving events may require a small reprocessing window and downstream deduplication.

Protect downstream systems

Do not export secrets or raw private content. Give the reporting workload a read key and isolate its destination credentials. Validate row count, schema, time boundaries, and null rates before replacing a production report.

See the full Query API reference, API error handling, and data retention guidance.