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

# Filtering

Our API supports filtering on all `/results` endpoints to refine query results. You can apply filters on both rows and columns to narrow down the data returned by the API. This feature is available for the following endpoints:

* [Get Execution Results](./endpoint/get-execution-result)
* [Get Execution Results CSV](./endpoint/get-execution-result-csv)
* [Get Query Results](./endpoint/get-query-result)
* [Get Query Results CSV](./endpoint/get-query-result-csv)

Filtering can be effectively used in conjunction with [pagination](./pagination) and [sorting](./sorting) to further enhance query efficiency and relevance.

### Filtering Parameters

#### `filters`

* **Type:** `string`
* **Description:** Allows specifying criteria to filter rows in the result set. It functions similarly to a SQL `WHERE` clause. If omitted, all results are returned.

<Note>
  - Use the format `<column_name> <operator> <value>` for criteria, for example, `block_time >= '2024-03-05 15:03'`.
  - Combine criteria using parentheses and logical operators `AND` / `OR`, e.g., `block_time >= '2024-03-05 15:03' AND (project = 'uniswap' OR project = 'balancer')`.
  - The `IN` operator is permitted, as in `tx_to IN (0x6a3e4b7e23661108aaec70266c468e6c679ae022, 0xdbf89389504e39f03fbb6bdd601aabb6bfbbed71)`.
  - The `NOT` operator is not supported; using `NOT IN` or `NOT LIKE` will produce an error.
  - For column names with special characters (e.g., spaces, emojis, dashes, dots), enclose them in double quotes: `"special, column" = 'ABC'`.
  - Values must be strings or numbers. SQL expressions like `now() - interval '1' day` are not allowed.
  - Dates and times should be formatted as strings, e.g., `block_time > '2023-01-03'`.
</Note>

#### `columns`

* **Type:** `string`
* **Description:** Specifies the column names to include in the result set. If omitted, all columns are returned.

<Note>
  - List column names without spaces, e.g., use `project,block_time,amount_usd` instead of `project, block_time, amount_usd`.
  - Specifying columns helps limit the results to essential data, reducing the data cost of the call.
</Note>

<Accordion title="Example filtering request">
  <Tabs>
    <Tab title="cURL">
      ```bash
      curl -X GET "https://api.dune.com/api/v1/query/{{query_id}}/results?limit=100&filters=block_time%20%3E%20'2024-03-05'&columns=tx_from,tx_to,tx_hash,amount_usd&sort_by=amount_usd%20desc,%20block_time" -H "x-dune-api-key: {{api_key}}"
      ```
    </Tab>

    <Tab title="Python">
      ```python
      import requests

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

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

      params = {
        "limit": 10, 
        "filters": "block_time > '2024-03-01'",
        "columns": "tx_from,tx_to,tx_hash,amount_usd",
        "sort_by": "amount_usd desc, block_time"
       }

      response = requests.request("GET", url, headers=headers, params=params)

      print(response.text)

      ```
    </Tab>

    <Tab title="Javascript">
      ```javascript

      const options = {
          method: 'GET',
          headers: {
              'X-DUNE-API-KEY': '<x-dune-api-key>'
          }
      };

      const queryParams = new URLSearchParams({
          limit: 10, 
          filters: "block_time > '2024-03-01'",
          columns: "tx_from,tx_to,tx_hash,amount_usd",
          sort_by: "amount_usd desc, block_time"
      });
      const url = `https://api.dune.com/api/v1/query/{query_id}/results?${queryParams}`;

      fetch(url, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));


      ```

      ```go Go

      package main

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

      func main() {
          url := "https://api.dune.com/api/v1/query/{query_id}/results"

          // Create query parameters
          params := url.Values{}
          params.Set("limit", 10)
          params.Set("filters", "block_time > '2024-03-01'")
          params.Set("columns", "tx_from,tx_to,tx_hash,amount_usd")
          params.Set("sort_by", "amount_usd desc, block_time")

          // Add parameters to URL
          fullURL := fmt.Sprintf("%s?%s", url, params.Encode())

          req, _ := http.NewRequest("GET", fullURL, 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))
      }
      ```
    </Tab>

    <Tab title="PHP">
      ```php
      <?php

      $curl = curl_init();

      $url = "https://api.dune.com/api/v1/query/{query_id}/results";
      $queryParams = http_build_query([
          'limit' => 10,
          'filters' => "block_time > '2024-03-01'",
          'columns' => "tx_from,tx_to,tx_hash,amount_usd",
          'sort_by' => "amount_usd desc, block_time",
      ]);
      $url .= '?' . $queryParams;

      curl_setopt_array($curl, [
          CURLOPT_URL => $url,
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_ENCODING => "",
          CURLOPT_MAXREDIRS => 10,
          CURLOPT_TIMEOUT => 30,
          CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
          CURLOPT_CUSTOMREQUEST => "GET",
          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;
      }
      ?>
      ```
    </Tab>

    <Tab title="Java">
      ```java

      import kong.unirest.HttpResponse;
      import kong.unirest.Unirest;

      public class Main {
          public static void main(String[] args) {
              HttpResponse<String> response = Unirest.get("https://api.dune.com/api/v1/query/{query_id}/results")
                      .header("X-DUNE-API-KEY", "<x-dune-api-key>")
                      .queryString("limit", 10)
                      .queryString("filters", "block_time > '2024-03-01'")
                      .queryString("columns", "tx_from,tx_to,tx_hash,amount_usd")
                      .queryString("sort_by", "amount_usd desc, block_time")
                      .asString();

              System.out.println(response.getBody());
          }
      }
      ```
    </Tab>
  </Tabs>
</Accordion>

### Filtered Response

<Accordion title="Example filtered response">
  ```json
      {
          "execution_id": "01HR8AGD6CWGHGP1BN3Z1SJ4MD",
          "query_id": 3493826,
          "is_execution_finished": true,
          "state": "QUERY_STATE_COMPLETED",
          "submitted_at": "2024-03-05T22:07:22.828653Z",
          "expires_at": "2024-06-03T22:07:53.36647Z",
          "execution_started_at": "2024-03-05T22:07:24.013663281Z",
          "execution_ended_at": "2024-03-05T22:07:53.366469062Z",
          "result": {
              "rows": [
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:50:59.000 UTC",
                      "tx_from": "0x38032f326436fdb9c7a9b359e90010f86b8ab482",
                      "tx_hash": "0xce6f59cf2f0b395d8fc33e49d1f5db5686be95555135fd8126bc7c59327cd9be",
                      "tx_to": "0x061b87122ed14b9526a813209c8a59a633257bab"
                  },
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:49:33.000 UTC",
                      "tx_from": "0xb46b909be665d75f833be22c6e6285ba5ad74dfa",
                      "tx_hash": "0x1f1725ebe374b1ffb50047055b793b2be6a8cb07ab75fd685b95e842953da4ca",
                      "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                  },
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:48:53.000 UTC",
                      "tx_from": "0x40014275b332f38423fa0de39939d26c7294ffc0",
                      "tx_hash": "0xb4364656c20007fb1d7bfa93d87fc6fe345a91b10661835d1a54d1ac7761a244",
                      "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                  },
                  {
                      "amount_usd": 1397.903560808159,
                      "block_time": "2024-03-05 20:48:03.000 UTC",
                      "tx_from": "0xb46b909be665d75f833be22c6e6285ba5ad74dfa",
                      "tx_hash": "0x818f701a6c7dcf78a090cfd8324da5896005c2a6d8e3ec5ac2c29cfa5e67f5d9",
                      "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                  },
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:47:55.000 UTC",
                      "tx_from": "0x50758bdc1735e94401ed73eb7e8bde482766819c",
                      "tx_hash": "0x1dc342dc397ffa7b433fa64280fe9f4a7e0b51409e9abc9fde61bc9b85c938be",
                      "tx_to": "0x4c4af8dbc524681930a27b2f1af5bcc8062e6fb7"
                  },
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:47:55.000 UTC",
                      "tx_from": "0x50758bdc1735e94401ed73eb7e8bde482766819c",
                      "tx_hash": "0x1dc342dc397ffa7b433fa64280fe9f4a7e0b51409e9abc9fde61bc9b85c938be",
                      "tx_to": "0x4c4af8dbc524681930a27b2f1af5bcc8062e6fb7"
                  },
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:47:53.000 UTC",
                      "tx_from": "0xfa3dc8db10e7c2f7dfa87e86bba6257066731bc1",
                      "tx_hash": "0x0d34634a9438ce241e2870b23e70a008c8db839ba38daadc1074c9b1a52be7c7",
                      "tx_to": "0xba12222222228d8ba445958a75a0704d566bf2c8"
                  },
                  {
                      "amount_usd": 2.753641952846242,
                      "block_time": "2024-03-05 20:47:53.000 UTC",
                      "tx_from": "0xfa3dc8db10e7c2f7dfa87e86bba6257066731bc1",
                      "tx_hash": "0x0d34634a9438ce241e2870b23e70a008c8db839ba38daadc1074c9b1a52be7c7",
                      "tx_to": "0xba12222222228d8ba445958a75a0704d566bf2c8"
                  },
                  {
                      "amount_usd": null,
                      "block_time": "2024-03-05 20:47:53.000 UTC",
                      "tx_from": "0xfa3dc8db10e7c2f7dfa87e86bba6257066731bc1",
                      "tx_hash": "0x0d34634a9438ce241e2870b23e70a008c8db839ba38daadc1074c9b1a52be7c7",
                      "tx_to": "0xba12222222228d8ba445958a75a0704d566bf2c8"
                  },
                  {
                      "amount_usd": 1798.8186143812122,
                      "block_time": "2024-03-05 20:47:49.000 UTC",
                      "tx_from": "0xb46b909be665d75f833be22c6e6285ba5ad74dfa",
                      "tx_hash": "0xcf8d9873f017a8ba9e624c3bb61bede8e11c194965690026cd394f20c55f896a",
                      "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                  }
              ],
              "metadata": {
                  "column_names": [
                      "block_time",
                      "tx_from",
                      "tx_to",
                      "tx_hash",
                      "amount_usd"
                  ],
                  "row_count": 10,
                  "result_set_bytes": 2042,
                  "total_row_count": 100,
                  "total_result_set_bytes": 56496,
                  "datapoint_count": 50,
                  "pending_time_millis": 1185,
                  "execution_time_millis": 29352
              }
          },
          "next_uri": "https://api.dune.com/api/v1/execution/01HR8AGD6CWGHGP1BN3Z1SJ4MD/results?columns=block_time%2Ctx_from%2Ctx_to%2Ctx_hash%2Camount_usd&filters=block_time+%3E+%272024-03-01%27&limit=10&offset=10",
          "next_offset": 10
      }
  ```
</Accordion>