Overview
The executions and results endpoints facilitate the execution of saved queries, retrieval of results in various formats, and management of query executions.
Queries, Executions, and Results
Results are linked to executions, and executions are tied to queries. Each execution has an execution_id. An execution_id is generated when you initiate the execution of a query through the execute query endpoint.
Unlike a query_id, which identifies a specific query, an execution_id represents a particular execution of that query. With an execution_id, you can monitor the execution’s status using the check status endpoint. The status can be one of the following: pending, success, or failure.
If an execution is successful, you can get the result using get result. Results are saved and can be retrieved multiple times. Results data from an execution are stored with an expiration date of 90 days (subject to change). This is visible on the API response on the “expires_at” field in the execution status and results json body (not on the CSV endpoint).
- Save your
execution_idfor later use without re-executing. - Use the get latest query result endpoint to fetch the most recent result.
- Understanding the differences and relationships between query results filters, schedules, executions, and params is crucial. Further details are provided below.
Query Filters vs. Execution Parameters
Two primary methods exist for fetching data from the Dune API while applying specific conditions:
Option 1: Utilize filters with the latest query result and employ schedules to maintain data freshness.
- Obtain the
query_id. - Use get latest query result endpoint to access the most recent results.
- Apply filters for desired data subsets.
- Implement schedules for maintaining data freshness.
Option 2: Execute a query with parameters to retrieve the desired subset of data.
- Obtain the
query_id. - Use execute query endpoint with parameters to trigger fresh execution.
- Grab the
execution_idfrom the response. - Fetch results via get execution result endpoint using the
execution_id.
Choosing Between Options
- Option 1 offers speed, as it builds upon existing results with filters. Use it when quick results are essential.
- Option 2 allows dynamic parameter passing for fresh executions. Employ it when real-time parameterization is required.
Endpoints
Below is an overview of each endpoint, providing a high-level understanding of their functionalities.
| Endpoint Title | Endpoint | Description |
|---|---|---|
| Cancel Execution | POST /v1/execution/{execution_id}/cancel | Cancels an ongoing query execution. Requires the execution_id. Returns a success boolean. |
| Execute Query | POST /v1/query/{query_id}/execute | Triggers an execution based on the query_id. Returns a execution_id. |
| Get Execution Status | GET /v1/execution/{execution_id}/status | Provides the status of a query execution give an execution_id. |
| Get Execution Result in CSV | GET /v1/execution/{execution_id}/results/csv | Retrieves the status, metadata, and results in CSV format. Includes data retention and limit information. |
| Get Execution Result | GET /v1/execution/{execution_id}/results | Fetches the execution status, metadata, and results in JSON format. Similar data handling as CSV endpoint. |
| Get Latest Query Result in CSV | GET /v1/query/{query_id}/results/csv | Returns the latest results of a query in CSV format, irrespective of the execution method. Queries must be public or owned. |
| Get Latest Query Result | GET /v1/query/{query_id}/results | Similar to the CSV endpoint but returns results in JSON format. Follows the same access and data limit policies. |
Was this page helpful?