Querying data through the API

To query your data through the API, use the query API. It explains how to send a JenQL query, read the results and run long queries in the background.

This page collects the habits that keep API queries fast and reliable.

1. Use the query API rather than list endpoints

The events and persons list endpoints are for quick lookups. For counting, grouping, exporting or anything that needs many pages, send a JenQL query instead.

2. Always filter by time

Events are stored by time, so a timestamp condition is the biggest single speed-up:

SELECT event, count()
FROM events
WHERE timestamp >= '2026-10-01' AND timestamp < '2026-10-08'
GROUP BY event

3. Select only the columns you need

SELECT * reads every property of every event. Name the columns and properties you need, such as timestamp, event, properties.$current_url.

4. Test in the SQL editor first

Write and check the query in the app's SQL editor, then copy the same text into your API request. Mistakes are easier to spot there, and the editor lists every table and column.

5. Use timestamp-based pagination instead of offset

To read a large result in pages, do not page with OFFSET. It gets slower with every page, because each page re-reads everything before it.

Instead, order by time and start each page where the previous one ended:

SELECT uuid, timestamp, event, distinct_id
FROM events
WHERE timestamp > '2026-10-01T00:00:00Z' AND timestamp < '2026-10-08T00:00:00Z'
ORDER BY timestamp
LIMIT 10000

For the next page, replace the start time with the timestamp of the last row you received. Several events can share a timestamp, so skip rows you already have by their uuid (or use >= with the last timestamp and drop the duplicates). Stop when a page returns fewer rows than the LIMIT.

The same applies to the events list endpoint: follow its next link, which pages by time, instead of using offset.

6. Run long queries in the background

For queries that may take more than a few seconds, send them with "refresh": "async" and check on them, as shown in long-running queries.

7. Reuse cached results

Repeating the same query within a short time returns cached results, which is fast. Only ask for force_blocking when you really need data from the last few moments.

8. Save queries your apps call often

If an app or dashboard calls the same query again and again, save it as an endpoint and call it by name.