Sampling

Our API supports sampling on all /results endpoints to provide a uniform sample of the dataset for efficient data analysis and visualization. This feature is particularly useful for use cases like charting (if you only have 4 000 pixels on the chart, then 10 000 datapoints are plenty), where analyzing a full dataset isn’t necessary. Sampling returns a subset (with a uniform distribution) of data, optimizing usage of very large results with reduced latency and costs. You can apply sampling to the following endpoints:

• Get Execution Results
• Get Execution Results CSV
• Get Query Results
• Get Query Results CSV

Sampling Parameters

sample_count

• Type: integer
• Description: Determines the number of rows to return as a sample from the result set. If the available dataset contains fewer rows than the specified sample_count, the entire dataset is returned.

• Sampling is designed to provide a randomized subset of data, with each request potentially producing different outcomes.
• When specifying sample_count (e.g., sample_count = 10000), the number is approximate. The actual number of rows returned may vary slightly (e.g., 10013, 10017), reflecting the probabilistic nature of the sampling process.
• sample_count is incompatible with offset, limit, and filters parameters.
• sample_count can be used with columns to specify which data fields to include in the sample.
• Specifying a low sample_count relative to total rows, being probabilistic, may return 0 rows due to the probability based sampling calculation (e.g., 10 in 100,000, means each row has ~0.01% chance to be included)

Example sampling request

• cURL
• Python
• Javascript

curl -X GET "https://api.dune.com/api/v1/query/{{query_id}}/results?sample_count=10000" -H "x-dune-api-key: {{api_key}}"

curl -X GET "https://api.dune.com/api/v1/query/{{query_id}}/results?sample_count=10000" -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 = {"sample_count": 10_000}

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({
    sample_count: 10000
});
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));

Sampling Response

Example sampling response

Showing trimmed reponse for sample_count=200 instead of specified sample_count=10000 in example request to not overwhelm the doc.

    {
        "execution_id": "01HR8D39V7N8WM653SVDW2G9WB",
        "query_id": 3494402,
        "is_execution_finished": true,
        "state": "QUERY_STATE_COMPLETED",
        "submitted_at": "2024-03-05T22:52:39.144099Z",
        "expires_at": "2024-06-03T22:54:03.004092Z",
        "execution_started_at": "2024-03-05T22:52:39.348798256Z",
        "execution_ended_at": "2024-03-05T22:54:03.00409093Z",
        "result": {
            "rows": [
                {
                    "amount_usd": 28.517144710689454,
                    "block_time": "2024-03-02 12:51:19.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 4892.433,
                    "block_time": "2024-03-05 13:42:59.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 31.579160400723985,
                    "block_time": "2024-03-04 20:17:56.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 84.162,
                    "block_time": "2024-03-05 07:26:54.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 1.5276341414539407,
                    "block_time": "2024-03-03 12:32:44.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 876.1714568508686,
                    "block_time": "2024-03-05 02:14:47.000 UTC",
                    "blockchain": "fantom"
                },
                {
                    "amount_usd": 4529.057,
                    "block_time": "2024-03-04 00:18:11.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 201.94357555355361,
                    "block_time": "2024-02-25 22:33:23.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 145.27394384575086,
                    "block_time": "2024-03-04 10:54:32.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 1070.7173780527592,
                    "block_time": "2024-03-04 13:57:21.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 223.82524240905198,
                    "block_time": "2024-03-02 08:31:15.000 UTC",
                    "blockchain": "polygon"
                },
                {
                    "amount_usd": 1950.3639893741088,
                    "block_time": "2024-03-03 05:09:47.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 719.5529722030446,
                    "block_time": "2024-03-05 09:27:23.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 6.89141479932381,
                    "block_time": "2024-03-01 03:35:39.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 368.6550396139464,
                    "block_time": "2024-03-04 11:05:35.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 105.21798800684901,
                    "block_time": "2024-03-05 16:04:47.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 31.17956089030626,
                    "block_time": "2024-03-05 18:17:05.000 UTC",
                    "blockchain": "polygon"
                },
                {
                    "amount_usd": 43.21002361278373,
                    "block_time": "2024-03-03 14:40:21.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 1448.8800596106462,
                    "block_time": "2024-03-02 12:47:21.000 UTC",
                    "blockchain": "base"
                },
                {
                    "amount_usd": 0.01001462,
                    "block_time": "2024-03-03 02:18:02.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 43.94295029931569,
                    "block_time": "2024-03-02 13:25:28.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 608.562,
                    "block_time": "2024-02-25 13:13:11.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 85.02994808708173,
                    "block_time": "2024-02-25 15:36:48.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 2849.089609803931,
                    "block_time": "2024-02-25 21:21:23.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 742.1382966435165,
                    "block_time": "2024-02-26 09:23:10.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 1523.857600998093,
                    "block_time": "2024-02-26 21:29:40.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 1.000853,
                    "block_time": "2024-02-25 22:25:16.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 187.32483603639648,
                    "block_time": "2024-02-26 05:38:59.000 UTC",
                    "blockchain": "ethereum"
                },
                {
                    "amount_usd": 9.365232080867631,
                    "block_time": "2024-03-04 21:59:33.000 UTC",
                    "blockchain": "polygon"
                },
                {
                    "amount_usd": 7.85318483149416,
                    "block_time": "2024-02-28 02:39:53.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 62.43033115744735,
                    "block_time": "2024-02-27 06:40:47.000 UTC",
                    "blockchain": "base"
                },
                {
                    "amount_usd": 245.49353625178662,
                    "block_time": "2024-02-27 08:02:35.000 UTC",
                    "blockchain": "bnb"
                },
                {
                    "amount_usd": 2.1101359357968,
                    "block_time": "2024-02-28 17:24:20.000 UTC",
                    "blockchain": "polygon"
                },
                {
                    "amount_usd": 887.988462523146,
                    "block_time": "2024-02-29 08:56:34.000 UTC",
                    "blockchain": "polygon"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-02-27 16:20:57.000 UTC",
                    "blockchain": "optimism"
                },
                {
                    "amount_usd": 0.9971501669140281,
                    "block_time": "2024-03-05 20:28:38.000 UTC",
                    "blockchain": "polygon"
                },
                {
                    "amount_usd": 16.03705776420069,
                    "block_time": "2024-03-03 23:27:03.000 UTC",
                    "blockchain": "base"
                },
                {
                    "amount_usd": 5.38636576521727,
                    "block_time": "2024-03-01 23:00:13.000 UTC",
                    "blockchain": "base"
                },
                {
                    "amount_usd": 30.130297357061917,
                    "block_time": "2024-02-27 02:20:07.000 UTC",
                    "blockchain": "bnb"
                }
            ],
            "metadata": {
                "column_names": [
                    "blockchain",
                    "block_time",
                    "amount_usd"
                ],
                "row_count": 213,
                "result_set_bytes": 12119,
                "total_row_count": 22325371,
                "total_result_set_bytes": 1175314615,
                "datapoint_count": 639,
                "pending_time_millis": 204,
                "execution_time_millis": 83655
            }
        }
    }