Skip to main content
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: 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

  • Python SDK
  • cURL
  • Python
  • Javascript
  • Go
  • PHP
  • Java
from dune_client.client import DuneClient

# setup Dune Python client
dune = DuneClient()

query_result = dune.get_latest_result_dataframe(
    query=3567562 # https://dune.com/queries/3567562
    , filters="overtip_amount > 0"
    , columns=["donor_fname","overtip_amount","days_overtipped","overall_tip_given_amount","overall_avg_tip_amount"]
    , sort_by=["overall_tip_given_amount desc"]
)

print(query_result)

​
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

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