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

# Execute Query

> Execute, or run a query for the specified query ID

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

<Accordion title="Execute query and get result in one call">
  <Tip> If you are using the [Python SDK](https://github.com/duneanalytics/dune-client/tree/d2195b2a9577e2dcae5d2600cb3eddce20987f38), you can directly execute and fetch result in one function call, like below: </Tip>

  Use `run_query` to get result in JSON,
  `run_query_csv` to get result in CSV format,
  and `run_query_dataframe` to get result in Pandas dataframe

  ```python Python SDK  theme={null}

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

  # setup Dune Python client
  dune = DuneClient()

  query = QueryBase(
      name="Sample Query",
      query_id=1215383,
  )

  result = dune.run_query(
      query = query,
      performance = 'large' # optionally define which tier to run the execution on (default is "medium")
  )

  # go over the results returned
  for row in result.result.rows: 
      print (row) # as an example we print the rows
  ```
</Accordion>

If the query has parameters and you don't add them in your API call, it will just run with the default params. You may add query parameters as part of the POST params data.

You can choose to include a `performance` parameter, by default it will use the "medium" performance tier. Credits are consumed based on actual compute resources used. "large" tier provides more resources for complex queries.

Returns an execution\_id associated with the triggered query execution and the state of the execution.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.dune.com/api/v1/query/{{query_id}}/execute"   \
    -H "X-Dune-API-Key: {{api_key}}"                                       \
    -H "Content-Type: application/json"                                   \
    -d '{"query_parameters": {"param1":24}, "performance": "large"}'
  ```

  ```python Python SDK theme={null}

  '''
  Download Dune Python SDK by running `pip install dune-client`
  For more info, visit the GitHub repository: https://github.com/duneanalytics/dune-client/tree/d2195b2a9577e2dcae5d2600cb3eddce20987f38
  '''

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

  # setup Dune Python client
  dune = DuneClient()

  # define the query to run
  query = QueryBase(
      name="Sample Query",
      query_id=1215383,
      params=[
          QueryParameter.text_type(name="TextField", value="Word"),
          QueryParameter.number_type(name="NumberField", value=3.1415926535),
          QueryParameter.date_type(name="DateField", value="2022-05-04 00:00:00"),
          QueryParameter.enum_type(name="ListField", value="Option 1"),
      ],
  )

  result = dune.execute_query(query = query # pass in the query we just defined
            , performance = "large" # define engine query is run on, default is "medium"
  )

  ```

  ```python Python theme={null}
  import requests

  url = "https://api.dune.com/api/v1/query/{query_id}/execute"

  headers = {"X-DUNE-API-KEY": "<x-dune-api-key>"}

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

  print(response.text)

  ```

  ```javascript Javascript theme={null}
  const options = {method: 'POST', headers: {'X-DUNE-API-KEY': '<x-dune-api-key>'}};

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

  ```

  ```go Go theme={null}
  package main

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

  func main() {

      url := "https://api.dune.com/api/v1/query/{query_id}/execute"

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

      req.Header.Add("X-DUNE-API-KEY", "<x-dune-api-key>")

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

      defer res.Body.Close()
      body, _ := ioutil.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/{query_id}/execute",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
      "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/{query_id}/execute")
  .header("X-DUNE-API-KEY", "<x-dune-api-key>")
  .asString();
  ```
</RequestExample>


## OpenAPI

````yaml POST /v1/query/{query_id}/execute
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/{query_id}/execute:
    post:
      summary: Execute, or run a query for the specified query ID
      description: Execute, or run a query for the specified query ID
      parameters:
        - description: API Key for the service
          in: header
          name: X-Dune-Api-Key
          required: true
          schema:
            type: string
        - description: Alternative to using the X-Dune-Api-Key header
          in: query
          name: api_key
          schema:
            type: string
        - description: Unique identifier of the query
          in: path
          name: query_id
          required: true
          schema:
            type: integer
        - description: >-
            The performance engine tier the execution will be run on. Can be
            `small`, `medium`, or `large`. Omit to use the default tier for the
            query engine. Credits are consumed based on actual compute resources
            used.
          in: query
          name: performance
          schema:
            enum:
              - small
              - medium
              - large
            type: string
        - description: >-
            SQL Query parameters in json key-value pairs. Each parameter is to
            be provided in key-value pairs. This enables you to execute a
            parameterized query with the provided values for your parameter
            keys. Partial submission of parameters is allowed. For example, if
            the query expects three parameters and you only pass in two, the
            third one will automatically use its default value as defined in the
            Query Parameter Editor page.
          in: query
          name: query_parameters
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ExecuteQueryResponse'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error404'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error500'
          description: Internal Server Error
components:
  schemas:
    models.ExecuteQueryResponse:
      properties:
        execution_id:
          example: 01HKZJ2683PHF9Q9PHHQ8FW4Q1
          type: string
        state:
          example: QUERY_STATE_PENDING
          type: string
      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.Error404:
      properties:
        error:
          example: Object not found
          type: string
      type: object
    models.Error500:
      properties:
        error:
          example: Internal error
          type: string
      type: object

````