> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> Minimum required API key scope: `Read/Write`

> [!NOTE]
>
> To access Query endpoints, an [Analyst plan](https://dune.com/pricing) or higher is required.

```bash cURL theme={null}
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
}'
```

```python Python SDK theme={null}
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
)
```

```python Python theme={null}
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)
```

```javascript JavaScript theme={null}
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));
```

```go Go theme={null}
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 PHP theme={null}
<?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;
}
```

```java Java theme={null}
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();
```


## OpenAPI

````yaml POST /v1/query
openapi: 3.0.1
info:
  contact: {}
  description: Dune API
  title: DuneAPI
  version: '1.0'
servers:
  - url: https://api.dune.com/api
security: []
paths:
  /v1/query:
    post:
      summary: Create and save a query on Dune
      description: |-
        This API allows for anyone to create a query.
        The owner of the query will be under the context of the API key.
      parameters:
        - description: API Key for the service
          in: header
          name: X-Dune-Api-Key
          required: true
          schema:
            type: string
        - description: API Key, alternative to using the HTTP header X-Dune-Api-Key
          in: query
          name: api_key
          schema:
            type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/models.CreateQueryRequest'
        description: CreateQueryRequest
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.CreateQueryResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error400'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error401'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error402'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error403'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error500'
          description: Internal Server Error
components:
  schemas:
    models.CreateQueryRequest:
      properties:
        description:
          description: The description of the created query.
          type: string
        is_private:
          description: >-
            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
          type: boolean
        is_temp:
          description: |-
            Indicates if the query is temporary (unsaved).
            Temporary queries can be executed but won't appear in the library.
          example: false
          type: boolean
        name:
          description: The name of the created query.
          type: string
        parameters:
          description: The parameters that the SQL query accepts.
          items:
            $ref: '#/components/schemas/models.Parameter'
          type: array
        query_sql:
          description: The SQL of the query.
          type: string
        tags:
          description: The tags of the query.
          items:
            type: string
          type: array
      required:
        - name
        - query_sql
      type: object
    models.CreateQueryResponse:
      properties:
        query_id:
          description: The Unique ID of the created query
          example: 1
          type: integer
      type: object
    models.Error400:
      properties:
        error:
          example: Bad Request
          type: string
      type: object
    models.Error401:
      properties:
        error:
          example: Invalid API Key
          type: string
      type: object
    models.Error402:
      properties:
        error:
          example: >-
            This API request would exceed your configured limits per billing
            cycle.
          type: string
      type: object
    models.Error403:
      properties:
        error:
          example: >-
            Not allowed to execute query. Query is archived, unsaved or not
            enough permissions
          type: string
      type: object
    models.Error500:
      properties:
        error:
          example: Internal error
          type: string
      type: object
    models.Parameter:
      properties:
        description:
          type: string
        enumFromResults:
          $ref: '#/components/schemas/models.EnumFromResults'
        enumOptions:
          items:
            type: string
          type: array
        isFreeformAllowed:
          type: boolean
        isMultiselect:
          type: boolean
        key:
          type: string
        type:
          type: string
        value:
          type: string
        values:
          items:
            type: string
          type: array
      type: object
    models.EnumFromResults:
      properties:
        columnName:
          type: string
        queryId:
          type: integer
      type: object

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.