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

<Info>
  Minimum required API key scope: `Read/Write`
</Info>

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

<RequestExample>
  ```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();
  ```
</RequestExample>


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

````