> ## 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.
# Pagination
Our API supports pagination on all `/results` endpoints to facilitate efficient data retrieval by dividing large datasets into smaller, manageable chunks. This feature helps prevent overload, ensures smoother performance, and enhances the user experience by making it easier to navigate through data, thus avoiding limit errors. Pagination 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)
Pagination can be effectively combined with [filtering](./filtering) and [sorting](./sorting) to optimize data fetching.
#### Example Paginating Request
```python theme={null}
# When using higher level functions like `get_latest_result_dataframe`,
# pagination via `limit` param is done automatically behind the scenes
# to get all rows in the result set.
#
# To actually paginate manually, i.e.,
# limit the number of rows each call returns,
# use a lower level function like `get_execution_results_csv`.
from dune_client.client import DuneClient
# setup Dune Python client
dune = DuneClient()
# Higher level function, let pagination be handled automatically and get full query result
query = QueryBase(
query_id=3567562 # https://dune.com/queries/3568055 -> DEX Pair Stats
)
query_result = dune.get_latest_result_dataframe(
query=query
, filters="overtip_amount > 0"
, sort_by=["overall_tip_given_amount desc"]
)
print(query_result)
# Lower level function, paginate manually to actually get a subset of results one chunk at a time
query_result2 = dune.get_execution_results(
job_id = '01HTJ5J9R1D366ZQ08S5B40P0W'
, limit = 100
, filters="overtip_amount > 0"
, sort_by=["overall_tip_given_amount desc"]
)
print("next_uri = " + query_result2.next_uri + "\n")
print("next_offset = " + str(query_result2.next_offset) + "\n")
print(query_result2.result.rows)
```
```bash theme={null}
curl -X GET 'https://api.dune.com/api/v1/query/{{query_id}}/results?limit=1000' -H 'x-dune-api-key: {{api_key}}'
```
```python theme={null}
import requests
url = "https://api.dune.com/api/v1/query/{query_id}/results"
headers = {"X-DUNE-API-KEY": ""}
params = {"limit": 1000, "offset": 0} # Define limit and offset parameters
response = requests.request("GET", url, headers=headers, params=params)
print(response.text)
```
```javascript theme={null}
const options = {
method: 'GET',
headers: {
'X-DUNE-API-KEY': ''
}
};
const queryParams = new URLSearchParams({limit: 1000, offset: 0}); // Define limit and offset parameters
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 theme={null}
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", "1000")
// 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", "")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```php theme={null}
1000,
'offset' => 0
]);
$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: "
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
?>
```
```java theme={null}
import kong.unirest.HttpResponse;
import kong.unirest.Unirest;
public class Main {
public static void main(String[] args) {
HttpResponse response = Unirest.get("https://api.dune.com/api/v1/query/{query_id}/results")
.header("X-DUNE-API-KEY", "")
.queryString("limit", 1000)
.queryString("offset", 0)
.asString();
System.out.println(response.getBody());
}
}
```
To paginate through results:
1. Use the `limit` parameter to set the maximum number of results per request.
2. The `offset` parameter defines the starting point for the data retrieval, with a default value of 0 (the first row).
3. For JSON responses, the `next_offset` and `next_uri` fields in the response body indicate how to fetch the next page. For CSV responses, look for the `X-Dune-Next-Offset` and `X-Dune-Next-Uri` headers. The server may adjust the provided limit if deemed too large, ensuring efficient data handling. Follow these indicators to navigate through the dataset seamlessly.
### Pagination Parameters
#### `limit` (required)
* **Type:** `integer`
* **Description:** Specifies the maximum number of rows to return in a single request, controlling the page size for pagination.
#### `offset`
* **Type:** `integer`
* **Description:** Determines the starting point for data retrieval, allowing for sequential access through the dataset.
* **Default:** 0 (the first row)
* **Usage:** Use in conjunction with `limit` to navigate through results in an efficient, incremental manner.
### Pagination in Response
The following fields in the response body are related to pagination and can be utilized when doing paginated get results request. If they are available, you can use them to paginate the next page. If they are not available, that means there are no more results to be fetched.
**`next_offset`**
* Type: Integer
* Description: Provides the offset to use for retrieving the next page of results, if available.
**`next_uri`**
* Type: String (URL)
* Description: Specifies the complete URI to retrieve the next page of results, if available.
**`x-dune-next-offset`**
* Type: Integer
* Description: Provides the offset to use for retrieving the next page of results, if available.
**`x-dune-next-uri`**
* Type: String (URL)
* Description: Specifies the complete URI to retrieve the next page of results, if available.
If you pass in an invalid `offset` parameter value, you will get an empty result set. For example, if there are only 25 rows of result data, and you pass in `offset=30`, you will **not** receive an error, but rather an empty result with metadata like this. Note the response field `result.total_row_count`, indicating this result has only 25 rows.
```json theme={null}
{
"execution_id": "01HPF1299EV69Z08DBKW1B6MJR",
"query_id": 2616430,
"is_execution_finished": true,
"state": "QUERY_STATE_COMPLETED",
"submitted_at": "2024-02-12T16:05:40.270193Z",
"expires_at": "2024-05-12T16:05:40.654018Z",
"execution_started_at": "2024-02-12T16:05:40.312207906Z",
"execution_ended_at": "2024-02-12T16:05:40.654017085Z",
"result": {
"rows": [],
"metadata": {
"column_names": [
"foo"
],
"row_count": 0,
"result_set_bytes": 0,
"total_row_count": 25,
"total_result_set_bytes": 28,
"datapoint_count": 0,
"pending_time_millis": 42,
"execution_time_millis": 341
}
}
}
```
```json theme={null}
{
"execution_id": "01HPFJ7VSFXPTA8WPMDKBXE167",
"query_id": 3426636,
"is_execution_finished": true,
"state": "QUERY_STATE_COMPLETED",
"submitted_at": "2024-02-12T21:05:48.848069Z",
"expires_at": "2024-05-12T21:05:50.199443Z",
"execution_started_at": "2024-02-12T21:05:48.863094766Z",
"execution_ended_at": "2024-02-12T21:05:50.199442351Z",
"result": {
"rows": [
{
"amount_usd": null,
"block_date": "2021-06-07 00:00:00.000 UTC",
"block_month": "2021-06-01T00:00:00Z",
"block_time": "2021-06-07 13:21:10.000 UTC",
"blockchain": "bnb",
"evt_index": 432,
"maker": null,
"project": "pancakeswap",
"project_contract_address": "0xa41e57459f09a126f358e118b693789d088ea8a0",
"taker": "0x88bf5a2e82510847e5dcbf33f44a9f611f1c1df5",
"token_bought_address": "0x85e76cbf4893c1fbcb34dcf1239a91ce2a4cf5a7",
"token_bought_amount": 2985.646787349244,
"token_bought_amount_raw": "2985646787349243786078",
"token_bought_symbol": "USDG",
"token_pair": "GMT-USDG",
"token_sold_address": "0x99e92123eb77bc8f999316f622e5222498438784",
"token_sold_amount": 192.8996462242313,
"token_sold_amount_raw": "192899646224231304314",
"token_sold_symbol": "GMT",
"tx_from": "0x88bf5a2e82510847e5dcbf33f44a9f611f1c1df5",
"tx_hash": "0xcee1e51083f28655fd9cc434238e2a243aa8f9bad20e717d145f246b5e73e231",
"tx_to": "0x10ed43c718714eb63d5aa57b78b54704e256024e"
},
{
"amount_usd": 0.0038254393551350966,
"block_date": "2021-06-27 00:00:00.000 UTC",
"block_month": "2021-06-01T00:00:00Z",
"block_time": "2021-06-27 19:21:48.000 UTC",
"blockchain": "bnb",
"evt_index": 38,
"maker": null,
"project": "pancakeswap",
"project_contract_address": "0x73c6542f8a529bf7bf0ac27a1d232a8525748738",
"taker": "0x10ed43c718714eb63d5aa57b78b54704e256024e",
"token_bought_address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
"token_bought_amount": 0.00001404037053195,
"token_bought_amount_raw": "14040370531950",
"token_bought_symbol": "WBNB",
"token_pair": null,
"token_sold_address": "0x3da1fd918a4c56b1cf6280ba37018c211db0d943",
"token_sold_amount": null,
"token_sold_amount_raw": "23274980840704048977780",
"token_sold_symbol": null,
"tx_from": "0xc0ffee00d263df1ecb44ece29f63a1e7479b7420",
"tx_hash": "0xa37ab410b4802e4d4aab950d1c3ce186abf4dbc98f7d7dbc54af17cf23519444",
"tx_to": "0x17f07d78e432b91ccfbed98f0617a83a4bfcc446"
},
{
"amount_usd": 229.4023072060263,
"block_date": "2021-06-29 00:00:00.000 UTC",
"block_month": "2021-06-01T00:00:00Z",
"block_time": "2021-06-29 23:23:56.000 UTC",
"blockchain": "bnb",
"evt_index": 51,
"maker": null,
"project": "pancakeswap",
"project_contract_address": "0x58f876857a02d6762e0101bb5c46a8c1ed44dc16",
"taker": "0xd7d116d7535aa724f8be9c482d2c768bc425a23c",
"token_bought_address": "0xe9e7cea3dedca5984780bafc599bd69add087d56",
"token_bought_amount": 229.23954712756574,
"token_bought_amount_raw": "229239547127565734569",
"token_bought_symbol": "BUSD",
"token_pair": "BUSD-WBNB",
"token_sold_address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
"token_sold_amount": 0.761872346852129,
"token_sold_amount_raw": "761872346852129018",
"token_sold_symbol": "WBNB",
"tx_from": "0xd7d116d7535aa724f8be9c482d2c768bc425a23c",
"tx_hash": "0x21429506dd0323b9ec40f4cf9314e58579aa25620bf95130f3a275a356ecd64c",
"tx_to": "0x10ed43c718714eb63d5aa57b78b54704e256024e"
},
{
"amount_usd": 2.668233112736453,
"block_date": "2021-06-04 00:00:00.000 UTC",
"block_month": "2021-06-01T00:00:00Z",
"block_time": "2021-06-04 00:11:44.000 UTC",
"blockchain": "bnb",
"evt_index": 384,
"maker": null,
"project": "pancakeswap",
"project_contract_address": "0x16b9a82891338f9ba80e2d6970fdda79d1eb0dae",
"taker": "0x452c012e55f7a27d3c25caf15fddfc5d63004cd5",
"token_bought_address": "0x55d398326f99059ff775485246999027b3197955",
"token_bought_amount": 2.662657507914879,
"token_bought_amount_raw": "2662657507914878729",
"token_bought_symbol": "USDT",
"token_pair": "USDT-WBNB",
"token_sold_address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
"token_sold_amount": 0.00632140891710662,
"token_sold_amount_raw": "6321408917106620",
"token_sold_symbol": "WBNB",
"tx_from": "0x452c012e55f7a27d3c25caf15fddfc5d63004cd5",
"tx_hash": "0x540ae87272f0fcce54595e7c2b67b9ef32cf2d0b5ccfa23c73a21727ae3350ba",
"tx_to": "0x10ed43c718714eb63d5aa57b78b54704e256024e"
},
{
"amount_usd": 46.95293131078031,
"block_date": "2021-06-25 00:00:00.000 UTC",
"block_month": "2021-06-01T00:00:00Z",
"block_time": "2021-06-25 18:24:20.000 UTC",
"blockchain": "bnb",
"evt_index": 105,
"maker": null,
"project": "pancakeswap",
"project_contract_address": "0x446f87f15d9a9f15b39d1b24d1d6d7e606e9d32d",
"taker": "0x10ed43c718714eb63d5aa57b78b54704e256024e",
"token_bought_address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
"token_bought_amount": 0.16652337675833562,
"token_bought_amount_raw": "166523376758335622",
"token_bought_symbol": "WBNB",
"token_pair": null,
"token_sold_address": "0x384f5a9b720349015a27251684c7a1510dd151ba",
"token_sold_amount": null,
"token_sold_amount_raw": "299011495590365081887",
"token_sold_symbol": null,
"tx_from": "0x60e028a06d04ecfd041ba415c3b8a63258a6506e",
"tx_hash": "0xf5e24e5024ff047210127c87cd12b475354ff84afc4bebc159066f9522daac73",
"tx_to": "0x10ed43c718714eb63d5aa57b78b54704e256024e"
}
],
"metadata": {
"column_names": [
"amount_usd",
"block_date",
"token_bought_symbol",
"token_pair",
"block_time",
"blockchain",
"evt_index",
"block_month",
"maker",
"project",
"project_contract_address",
"taker",
"token_bought_address",
"token_bought_amount",
"token_bought_amount_raw",
"token_sold_address",
"token_sold_amount",
"token_sold_amount_raw",
"token_sold_symbol",
"tx_from",
"tx_hash",
"tx_to"
],
"row_count": 5,
"result_set_bytes": 0,
"total_row_count": 10,
"total_result_set_bytes": 5639,
"datapoint_count": 110,
"pending_time_millis": 15,
"execution_time_millis": 1336
}
},
"next_uri": "https://api.dune.com/api/v1/execution/01HPFJ7VSFXPTA8WPMDKBXE167/results?limit=1000&offset=5",
"next_offset": 5
}
```
**Data Returned Limit**
When using pagination, our intention is to use sizes that work well on mobile, with lower data and ram consumption. For this, and to avoid more work on the developer, when the client specifies a very large limit value (for example 500000 rows), instead of returning an error, the server will override this limit to a lower, safer value (for example 30000 rows) and *will always provide* the correct next `offset` and `limit` value to use on the next paginated requests. The exact maximum limit value is subject to change.
**Data Size Limit**
Dune internally has a maximum query result size limit (which currently is 32GB). If your query yields more than 32GB of data, the result will be truncated in storage. In such cases, pulling the result data (using pagination) but without specifying `allow_partial_results` set to true will trigger an error message: "error": "Partial Result, please request with 'allows\_partial\_results=true'". If you wish to retrieve partial results, you can pass the parameter `allow_partial_results=true`. But please make sure you indeed want to fetch the truncated result.
So what? Related to pagination, this means that
* For query results under 32GB, use the API as normal.
* When your query results exceed 32GB, in addition to `limit` and `offset` parameters in order to read the partial result (the first 32GB of data), set `allow_partial_results=true`
* You can use the [Get Status API](./endpoint/get-execution-status) to check the size of your result, `result.result_set_size`