Pull query results via the API

This walks through the most common integration: run a saved query on demand and get its data back, end to end.

1. Trigger the query

Two endpoints can start a run — pick based on whether you want the run to show up in the query’s run history:

• POST /api/queries/{id}/refresh — ad-hoc cache-or-enqueue (see the async query model). Fastest path if all you want is fresh data.
• POST /api/queries/{id}/run — goes through the runs pipeline, so it shows up in GET /api/runs history and its result becomes CSV-downloadable by run id. See the Queries reference.

Either way, the response is one of two shapes:

// immediate result:
{ "query_result": { "id": 501, "data": { "...": "..." }, "runtime": 0.42 } }

// or an enqueued job:
{ "job": { "id": 9001, "status": 1, "query_result_id": null } }

2. If you got a job, poll it

GET /api/jobs/{id}

Keep polling until status is 3 (Success), 4 (Failure), or 5 (Cancelled) — 1 (Pending) and 2 (Started) are the only non-terminal states. See the Jobs reference.

3. Fetch the result

Once the job succeeds, it carries a query_result_id. Fetch the actual data with:

GET /api/query_results/{query_result_id}

See the Query results reference for the response shape, and its .{format} variant for downloading the same result as CSV/TSV/XLSX/JSON directly.

4. Passing parameters

If the query has parameters, supply runtime values on POST /api/queries/{id}/results (the saved-query execute endpoint) as {"parameters": {...}} — the parameter definitions already live on the saved query, so you only need to send values. See the Queries reference.

Exporting a specific run’s result

If you triggered the run via POST /api/queries/{id}/run (not refresh), you can download that exact run’s data directly:

GET /api/runs/{id}/result.csv

See the Runs reference. This 404s if the run failed or its result has since been garbage-collected — for anything you need to keep, fetch it promptly after the run finishes.