Run Saved Query
Execute a previously saved query definition against its bound or a specified dataset.
/v1/query/{query_id}
curl -X POST "https://analytics.toolkitapi.io/v1/query/qry_xyz789" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "dset_abc123",
"parameters": {
"month": "2024-05"
}
}'
import httpx
resp = httpx.post(
"https://analytics.toolkitapi.io/v1/query/qry_xyz789",
json={
"dataset_id": "dset_abc123",
"parameters": {
"month": "2024-05"
}
},
)
print(resp.json())const resp = await fetch("https://analytics.toolkitapi.io/v1/query/qry_xyz789", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"dataset_id": "dset_abc123",
"parameters": {
"month": "2024-05"
}
}),
});
const data = await resp.json();
console.log(data);# See curl example{
"query_id": "qry_xyz789",
"dataset_id": "dset_abc123",
"execution_mode": "sync",
"status": "succeeded",
"results": {
"columns": ["region", "total_revenue"],
"rows": [
["North", 48320.50],
["South", 31205.00],
["East", 27890.75],
["West", 19450.25]
],
"row_count": 4
},
"job_id": null,
"created_at": "2024-06-01T14:22:10Z"
}Description
How to Use
1. Save a query with `POST /v1/save` and note the returned `query_id`. 2. Call `POST /v1/query/{query_id}` with the `dataset_id` you want to run it against. 3. For large datasets, set `"execution_mode": "async"` — you will receive a `job_id` in the response. 4. Poll `GET /v1/jobs/{job_id}` until `status` is `"succeeded"` or `"failed"`. 5. Parse the `results.rows` array for downstream use.
About This Tool
The Run Saved Query endpoint executes a query definition that was previously stored via `POST /v1/save`. It supports both synchronous and asynchronous execution modes, making it suitable for quick lookups as well as long-running aggregations over large datasets.
When running synchronously, results are returned inline in the response. For async execution, a `job_id` is returned and you poll `GET /v1/jobs/{job_id}` for completion.
Why Use This Tool
- Recurring reports — Run the same named query each day/week against a fresh uploaded dataset.
- Parameterised queries — Pass runtime `parameters` (e.g. date ranges, region filters) to re-use one definition across multiple slices.
- Async large-dataset analysis — Offload heavy computations and retrieve results when ready.
- API-driven dashboards — Back each dashboard widget with a dedicated saved query, executing all in parallel.
- Automated pipelines — Trigger query execution from CI/CD or data pipelines after each data refresh.
Start using Run Saved Query now
Get your free API key and make your first request in under a minute.