Read Query

This API allows for anyone to read the sql text, parameters, name, tags, and state of a query. For private queries, only the API key generated under the context of the owner of that query will work.

To access Query endpoints, a Plus plan or higher is required.

cURL

curl --request GET \
  --url https://api.dune.com/api/v1/query/{queryId} \
  --header 'X-DUNE-API-KEY: <x-dune-api-key>'

Headers

X-DUNE-API-KEY

string

required

API Key for the service

Path Parameters

queryId

integer

required

unique identifier of the query

Query Parameters

api_key

string

API Key for the service, alternative to using the HTTP header X-DUNE-API-KEY.

Response

200

application/json

OK

query_id

integer

Unique identifier of the query.

Example:

1252207

name

string

Name of the query.

Example:

"erc20 balances (user address) API"

description

string

Description of the query.

Example:

"Example Blockchain Query"

tags

string[]

Tags associated with the query.

Example:

["erc20", "balances", "user address"]

version

integer

Version of the query.

Example:

17

parameters

object[]

Show child attributes

parameters.key

string

required

The key name of the parameter.

parameters.description

string

A brief description of the parameter.

parameters.value

string

The default value used by this parameter during execution, format depends on the type.

parameters.values

string[]

An array of string values, used when multiple selections are allowed.

parameters.type

enum<string>

The type of the parameter, determines the format of 'value(s)'. 'number': Numeric parameters, the value must be a number (e.g., '20'). 'text': String parameters, value can be any text including hex 0x-prefixed values (e.g., '0xae2fc...'), an empty value defaults to an empty string. 'datetime': Date and time parameters, value must be in 'YYYY-MM-DD hh:mm:ss' format (e.g., '2021-12-31 23:59:59'). 'enum': Parameters with a specific list of values, 'EnumValues' field is mandatory, providing a JSON list of strings representing valid options, the 'value' must be one of these options (e.g., 'Option1').

Available options:

number,

text,

datetime,

enum

parameters.EnumValues

string[]

List of valid options for 'enum' type parameters.

parameters.isMultiselect

boolean

Indicates if multiple selections are allowed for this parameter.

parameters.isFreeformAllowed

boolean

Indicates if freeform input is allowed for this parameter.

parameters.enumFromResults

object

Show child attributes

parameters.enumFromResults.queryId

integer

The ID of the query to fetch results from.

parameters.enumFromResults.columnName

string

The column name to use from the query results.

Example:

[
  {
    "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"
    ]
  },
  {
    "key": "dust",
    "value": "keep",
    "type": "enum",
    "enumOptions": ["keep", "remove"]
  }
]

query_engine

string

The query engine used to execute the query.

Example:

"v2 Dune SQL"

query_sql

string

The SQL query text.

Example:

"with\n erc20_balances as (\n WITH erc20_in as ( \n SELECT \n contract_address\n , SUM(tr.value) as token_funded\n FROM erc20_{{chain}}.evt_Transfer tr\n WHERE tr.to = {{address}}\n AND ({{blocknumber}} = 0 OR tr.evt_block_number <= {{blocknumber}})\n GROUP BY 1\n ),\n \n erc20_out as (\n SELECT \n contract_address\n , SUM(tr.value) as token_spent\n FROM erc20_{{chain}}.evt_Transfer tr\n WHERE tr.\"from\" = {{address}}\n AND ({{blocknumber}} = 0 OR tr.evt_block_number <= {{blocknumber}})\n GROUP BY 1\n )\n \n SELECT\n tk.symbol as symbol\n , erc20_in.contract_address\n , (cast(token_funded as double) - COALESCE(cast(token_spent as double), 0))/pow(10,COALESCE(tk.decimals,18)) as balance\n FROM erc20_in\n LEFT JOIN erc20_out ON erc20_in.contract_address = erc20_out.contract_address\n LEFT JOIN tokens.erc20 tk ON tk.contract_address = erc20_in.contract_address\n WHERE cast(token_funded as double) - COALESCE(cast(token_spent as double), 0) > 0\n -- WHERE tk.symbol is not null\n )\n\nSELECT\n bal.symbol\n , round(bal.balance,5) as notional_value\n , round(bal.balance*p.price,3) as total_value\n , p.price as token_price\nFROM erc20_balances bal\nLEFT JOIN prices.usd_latest p \n ON p.contract_address = bal.contract_address\n AND p.blockchain = '{{chain}}' --AND p.rn = 1 \nWHERE bal.balance > 0\nAND ('{{dust}}' = 'keep' OR bal.balance*p.price > 0.01)\nORDER BY total_value DESC\nNULLS LAST"

is_private

boolean

Indicates if the query is private.

Example:

false

is_archived

boolean

Indicates if the query is archived.

Example:

false

is_unsaved

boolean

Indicates if the query is unsaved.

Example:

false

owner

string

The owner of the query.

Example:

"Dune"