Overview

These query management endpoints help you programmatically create and manage Dune SQL queries via the API, ideal for integration with GitHub or other CI/CD pipelines.

Queries

Queries all have a query id which is returned when you read/create a query. You can also find it within a url, i.e. https://dune.com/queries/<query_id>/<visualization_id>.

Each query comes with fields you can edit such as:

• name: query name text
• description: query description text
• query_sql: the raw sql text
• params: parameters within the query, using the {{ foo }} syntax. See the section below for more details.
• is_private: boolean for if query is private or not. Private queries cannot be found or queried by others.
• archived: boolean for if query is archived or not. Archived queries cannot be run or edited by anyone.

Query Parameters

There are four kinds of parameters you can use in a Dune query (these are not API parameters).

• number
• text
• date
• enum (called a list in the UI)

For passing these parameters through the API request body, you can use the following format for executions:

{
"foo": "value",
"bar":1000, 
"baz": "2020-12-01T01:20:30Z"
}

Where “foo”, “bar”, and “baz” are three params in a query. If you leave one out, it goes with the default param value.

For Queries endpoints, you’ll need to define the type and more:

[
    {
        "key": "block_time_start",
        "type": "datetime",
        "value": "2017-01-01 00:00:00"
    },
    {
        "key": "from",
        "type": "text",
        "value": "0xae2fc483527b8ef99eb5d9b44875f005ba1fae13"
    },
    {
        "key": "limit",
        "type": "number",
        "value": "20"
    },
    {
        "key": "type",
        "type": "enum",
        "value": "DynamicFee",
        "enumOptions": [
            "DynamicFee",
            "Legacy"
        ]
    }
]

Note that the datetime parameter type requires you use the syntax timestamp '{{block_time_start}}' to cast the parameter to a timestamp.

If you are using bytearrays/binary (0x1234...), then you will still pass it as text through the API but ensure your SQL text puts the parameter without any quotes around it.

If you’re using the Dune Python SDK, check out the sdk doc page for an example.

Endpoints

Endpoint Title	Endpoint	Description
List Queries	GET /v1/queries	Retrieves a paginated list of queries
Get Query Pipeline	GET /v1/query/{query_id}/pipeline	Retrieves the pipeline definition for a query, including dependencies and execution order
Read Query	GET /v1/query/{query_id}	Fetches details of a specific query by ID
Create Query	POST /v1/query	Creates a new query with specified parameters
Update Query	PATCH /v1/query/{query_id}	Updates an existing query’s properties
Archive Query	PATCH /v1/query/{query_id}/archive	Archives a query, preventing it from being run or edited
Unarchive Query	PATCH /v1/query/{query_id}/unarchive	Unarchives a previously archived query
Make Query Private	PATCH /v1/query/{query_id}/private	Makes a query private, restricting access
Make Query Public	PATCH /v1/query/{query_id}/unprivate	Makes a private query public