Create Query

This API allows for anyone to create a query. The owner of the query will be under the context of the API key.

POST /v1/query

cURL

curl --request POST \
  --url https://api.dune.com/api/v1/query \
  --header 'Content-Type: application/json' \
  --header 'X-DUNE-API-KEY: <x-dune-api-key>' \
  --data '{
  "name": "erc20 balances (user address) API",
  "description": "Example Blockchain Query",
  "parameters": [
    {
      "key": "address",
      "value": "0x2ae8c972fb2e6c00dded8986e2dc672ed190da06",
      "type": "text"
    },
    {
      "key": "blocknumber",
      "value": "0",
      "type": "number"
    },
    {
      "key": "chain",
      "value": "ethereum",
      "type": "enum",
      "enumOptions": [
        "ethereum",
        "polygon",
        "optimism",
        "arbitrum",
        "avalanche_c",
        "gnosis",
        "bnb"
      ]
    }
  ],
  "query_sql": "SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}",
  "is_private": true
}'

from dune_client.types import QueryParameter
from dune_client.client import DuneClient
from dune_client.query import QueryBase

dune = DuneClient()

query = dune.create_query(
    name="Example Blockchain Query",
    query_sql="SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}",
    params=[
        QueryParameter.number_type(name="blocknumber", value=0),
        QueryParameter.text_type(name="address", value="0x2ae8c972fb2e6c00dded8986e2dc672ed190da06"),
        QueryParameter.text_type(name="blockchain", value="ethereum"),
    ],
    is_private=False
)

import requests

url = "https://api.dune.com/api/v1/query"

payload = {
    "name": "erc20 balances (user address) API",
    "description": "Example Blockchain Query",
    "parameters": [
        {
            "key": "address",
            "value": "0x2ae8c972fb2e6c00dded8986e2dc672ed190da06",
            "type": "text"
        },
        {
            "key": "blocknumber",
            "value": "0",
            "type": "number"
        },
        {
            "key": "chain",
            "value": "ethereum",
            "type": "enum",
            "enumOptions": ["ethereum", "polygon", "optimism", "arbitrum", "avalanche_c", "gnosis", "bnb"]
        }
    ],
    "query_sql": "SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}",
    "is_private": True
}
headers = {
    "X-DUNE-API-KEY": "<x-dune-api-key>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-DUNE-API-KEY': '<x-dune-api-key>', 'Content-Type': 'application/json'},
  body: '{"name":"erc20 balances (user address) API","description":"Example Blockchain Query","parameters":[{"key":"address","value":"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06","type":"text"},{"key":"blocknumber","value":"0","type":"number"},{"key":"chain","value":"ethereum","type":"enum","enumOptions":["ethereum","polygon","optimism","arbitrum","avalanche_c","gnosis","bnb"]}],"query_sql":"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}","is_private":true}'
};

fetch('https://api.dune.com/api/v1/query', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dune.com/api/v1/query"

	payload := strings.NewReader("{\n  \"name\": \"erc20 balances (user address) API\",\n  \"description\": \"Example Blockchain Query\",\n  \"parameters\": [\n    {\n      \"key\": \"address\",\n      \"value\": \"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06\",\n      \"type\": \"text\"\n    },\n    {\n      \"key\": \"blocknumber\",\n      \"value\": \"0\",\n      \"type\": \"number\"\n    },\n    {\n      \"key\": \"chain\",\n      \"value\": \"ethereum\",\n      \"type\": \"enum\",\n      \"enumOptions\": [\n        \"ethereum\",\n        \"polygon\",\n        \"optimism\",\n        \"arbitrum\",\n        \"avalanche_c\",\n        \"gnosis\",\n        \"bnb\"\n      ]\n    }\n  ],\n  \"query_sql\": \"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}\",\n  \"is_private\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-DUNE-API-KEY", "<x-dune-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dune.com/api/v1/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"name\": \"erc20 balances (user address) API\",\n  \"description\": \"Example Blockchain Query\",\n  \"parameters\": [\n    {\n      \"key\": \"address\",\n      \"value\": \"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06\",\n      \"type\": \"text\"\n    },\n    {\n      \"key\": \"blocknumber\",\n      \"value\": \"0\",\n      \"type\": \"number\"\n    },\n    {\n      \"key\": \"chain\",\n      \"value\": \"ethereum\",\n      \"type\": \"enum\",\n      \"enumOptions\": [\n        \"ethereum\",\n        \"polygon\",\n        \"optimism\",\n        \"arbitrum\",\n        \"avalanche_c\",\n        \"gnosis\",\n        \"bnb\"\n      ]\n    }\n  ],\n  \"query_sql\": \"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}\",\n  \"is_private\": true\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-DUNE-API-KEY: <x-dune-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.dune.com/api/v1/query")
  .header("X-DUNE-API-KEY", "<x-dune-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"erc20 balances (user address) API\",\n  \"description\": \"Example Blockchain Query\",\n  \"parameters\": [\n    {\n      \"key\": \"address\",\n      \"value\": \"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06\",\n      \"type\": \"text\"\n    },\n    {\n      \"key\": \"blocknumber\",\n      \"value\": \"0\",\n      \"type\": \"number\"\n    },\n    {\n      \"key\": \"chain\",\n      \"value\": \"ethereum\",\n      \"type\": \"enum\",\n      \"enumOptions\": [\n        \"ethereum\",\n        \"polygon\",\n        \"optimism\",\n        \"arbitrum\",\n        \"avalanche_c\",\n        \"gnosis\",\n        \"bnb\"\n      ]\n    }\n  ],\n  \"query_sql\": \"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}\",\n  \"is_private\": true\n}")
  .asString();

200

{
  "query_id": 1
}

{
  "error": "Bad Request"
}

{
  "error": "Invalid API Key"
}

{
  "error": "This API request would exceed your configured limits per billing cycle."
}

{
  "error": "Not allowed to execute query. Query is archived, unsaved or not enough permissions"
}

{
  "error": "Internal error"
}

Minimum required API key scope: Read/Write

To access Query endpoints, an Analyst plan or higher is required.

cURL

curl --request POST \
  --url https://api.dune.com/api/v1/query \
  --header 'Content-Type: application/json' \
  --header 'X-DUNE-API-KEY: <x-dune-api-key>' \
  --data '{
  "name": "erc20 balances (user address) API",
  "description": "Example Blockchain Query",
  "parameters": [
    {
      "key": "address",
      "value": "0x2ae8c972fb2e6c00dded8986e2dc672ed190da06",
      "type": "text"
    },
    {
      "key": "blocknumber",
      "value": "0",
      "type": "number"
    },
    {
      "key": "chain",
      "value": "ethereum",
      "type": "enum",
      "enumOptions": [
        "ethereum",
        "polygon",
        "optimism",
        "arbitrum",
        "avalanche_c",
        "gnosis",
        "bnb"
      ]
    }
  ],
  "query_sql": "SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}",
  "is_private": true
}'

from dune_client.types import QueryParameter
from dune_client.client import DuneClient
from dune_client.query import QueryBase

dune = DuneClient()

query = dune.create_query(
    name="Example Blockchain Query",
    query_sql="SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}",
    params=[
        QueryParameter.number_type(name="blocknumber", value=0),
        QueryParameter.text_type(name="address", value="0x2ae8c972fb2e6c00dded8986e2dc672ed190da06"),
        QueryParameter.text_type(name="blockchain", value="ethereum"),
    ],
    is_private=False
)

import requests

url = "https://api.dune.com/api/v1/query"

payload = {
    "name": "erc20 balances (user address) API",
    "description": "Example Blockchain Query",
    "parameters": [
        {
            "key": "address",
            "value": "0x2ae8c972fb2e6c00dded8986e2dc672ed190da06",
            "type": "text"
        },
        {
            "key": "blocknumber",
            "value": "0",
            "type": "number"
        },
        {
            "key": "chain",
            "value": "ethereum",
            "type": "enum",
            "enumOptions": ["ethereum", "polygon", "optimism", "arbitrum", "avalanche_c", "gnosis", "bnb"]
        }
    ],
    "query_sql": "SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}",
    "is_private": True
}
headers = {
    "X-DUNE-API-KEY": "<x-dune-api-key>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-DUNE-API-KEY': '<x-dune-api-key>', 'Content-Type': 'application/json'},
  body: '{"name":"erc20 balances (user address) API","description":"Example Blockchain Query","parameters":[{"key":"address","value":"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06","type":"text"},{"key":"blocknumber","value":"0","type":"number"},{"key":"chain","value":"ethereum","type":"enum","enumOptions":["ethereum","polygon","optimism","arbitrum","avalanche_c","gnosis","bnb"]}],"query_sql":"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}","is_private":true}'
};

fetch('https://api.dune.com/api/v1/query', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dune.com/api/v1/query"

	payload := strings.NewReader("{\n  \"name\": \"erc20 balances (user address) API\",\n  \"description\": \"Example Blockchain Query\",\n  \"parameters\": [\n    {\n      \"key\": \"address\",\n      \"value\": \"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06\",\n      \"type\": \"text\"\n    },\n    {\n      \"key\": \"blocknumber\",\n      \"value\": \"0\",\n      \"type\": \"number\"\n    },\n    {\n      \"key\": \"chain\",\n      \"value\": \"ethereum\",\n      \"type\": \"enum\",\n      \"enumOptions\": [\n        \"ethereum\",\n        \"polygon\",\n        \"optimism\",\n        \"arbitrum\",\n        \"avalanche_c\",\n        \"gnosis\",\n        \"bnb\"\n      ]\n    }\n  ],\n  \"query_sql\": \"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}\",\n  \"is_private\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-DUNE-API-KEY", "<x-dune-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dune.com/api/v1/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"name\": \"erc20 balances (user address) API\",\n  \"description\": \"Example Blockchain Query\",\n  \"parameters\": [\n    {\n      \"key\": \"address\",\n      \"value\": \"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06\",\n      \"type\": \"text\"\n    },\n    {\n      \"key\": \"blocknumber\",\n      \"value\": \"0\",\n      \"type\": \"number\"\n    },\n    {\n      \"key\": \"chain\",\n      \"value\": \"ethereum\",\n      \"type\": \"enum\",\n      \"enumOptions\": [\n        \"ethereum\",\n        \"polygon\",\n        \"optimism\",\n        \"arbitrum\",\n        \"avalanche_c\",\n        \"gnosis\",\n        \"bnb\"\n      ]\n    }\n  ],\n  \"query_sql\": \"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}\",\n  \"is_private\": true\n}",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-DUNE-API-KEY: <x-dune-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.dune.com/api/v1/query")
  .header("X-DUNE-API-KEY", "<x-dune-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"erc20 balances (user address) API\",\n  \"description\": \"Example Blockchain Query\",\n  \"parameters\": [\n    {\n      \"key\": \"address\",\n      \"value\": \"0x2ae8c972fb2e6c00dded8986e2dc672ed190da06\",\n      \"type\": \"text\"\n    },\n    {\n      \"key\": \"blocknumber\",\n      \"value\": \"0\",\n      \"type\": \"number\"\n    },\n    {\n      \"key\": \"chain\",\n      \"value\": \"ethereum\",\n      \"type\": \"enum\",\n      \"enumOptions\": [\n        \"ethereum\",\n        \"polygon\",\n        \"optimism\",\n        \"arbitrum\",\n        \"avalanche_c\",\n        \"gnosis\",\n        \"bnb\"\n      ]\n    }\n  ],\n  \"query_sql\": \"SELECT * FROM {{blockchain}}.transactions WHERE to = {{address}} AND block_number > {{blocknumber}}\",\n  \"is_private\": true\n}")
  .asString();

Headers

X-Dune-Api-Key · string · required

API Key for the service

Query Parameters

api_key · string

API Key, alternative to using the HTTP header X-Dune-Api-Key

Body

*/*

CreateQueryRequest

name · string · required

The name of the created query.

query_sql · string · required

The SQL of the query.

description · string

The description of the created query.

is_private · boolean

Indicates if the query is private, meaning that only the team or, in case of personal queries, the user that created it can see it.

Example:

true

is_temp · boolean

Indicates if the query is temporary (unsaved). Temporary queries can be executed but won't appear in the library.

Example:

false

parameters · object[]

The parameters that the SQL query accepts.

Show child attributes

tags · string[]

The tags of the query.

Response

200

application/json

OK

query_id · integer

The Unique ID of the created query

Example:

1