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
• Get Execution Results CSV
• Get Query Results
• Get Query Results CSV

Filtering can be effectively used in conjunction with pagination and sorting to further enhance query efficiency and relevance. See an example of filtering in action with this Dune farcaster frame.

Example Filtering Request

cURL

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}}"

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}}"

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)

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));

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))
}

<?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;
}
?>

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());
    }
}

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.

• 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'.

columns

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

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

Filtered Response

Example filtered response

    {
        "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
    }