Overview

These query management endspoints 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 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 valiue.

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.