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_id for 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.

1. Obtain the query_id.
2. Use get latest query result endpoint to access the most recent results.
3. Apply filters for desired data subsets.
4. Implement schedules for maintaining data freshness.

Option 2: Execute a query with parameters to retrieve the desired subset of data.

1. Obtain the query_id.
2. Use execute query endpoint with parameters to trigger fresh execution.
3. Grab the execution_id from the response.
4. 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
Execute SQL	POST /v1/sql/execute	Executes arbitrary SQL queries directly. Returns an execution_id to track the query execution.
Execute Query	POST /v1/query/{query_id}/execute	Triggers an execution based on the query_id. Returns an execution_id.
Execute Query Pipeline	POST /v1/query/{query_id}/pipeline/execute	Executes a query pipeline with all its dependencies. Returns a pipeline_execution_id.
Get Execution Status	GET /v1/execution/{execution_id}/status	Provides the status of a query execution given an execution_id.
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 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 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.
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.
Cancel Execution	POST /v1/execution/{execution_id}/cancel	Cancels an ongoing query execution. Requires the execution_id. Returns a success boolean.