Client SDKs - Dune Docs

Dune provides official SDKs that make it easy to interact with our API. All SDKs include a powerful execute() function that handles polling, pagination, and error handling automatically.

New: All SDKs now include an execute() function that automatically handles:

Query execution submission
Polling for completion
Automatic pagination for large result sets
Error handling and retries
Result formatting

No more manual polling or pagination logic!

Python

The Python SDK is our most mature and feature-complete client.

Installation

pip install dune-client

Always use the latest release. Check releases page for the current version. Features in the main branch may not be released yet.

Quick Start

from dune_client import DuneClient

# DuneClient will read the DUNE_API_KEY environment variable
dune = DuneClient()

# Execute a query by ID
results = dune.execute(query_id=3493826)

# Or execute raw SQL
results = dune.execute(sql="SELECT * FROM dex.trades LIMIT 10")

# Access results
for row in results.rows:
    print(row)

The execute() Function

The execute() function is the simplest way to run queries and get results:

from dune_client import DuneClient

dune = DuneClient(api_key="YOUR_API_KEY")

# Execute a saved query
results = dune.execute(
    query_id=3493826,
    performance="medium",  # or "large"
    params={
        "blockchain": "ethereum",
        "min_volume": 1000
    }
)

print(f"Got {len(results.rows)} rows")

from dune_client import DuneClient

dune = DuneClient(api_key="YOUR_API_KEY")

# Execute arbitrary SQL
sql = """
SELECT 
    blockchain,
    SUM(amount_usd) as volume
FROM dex.trades
WHERE block_time > now() - interval '24' hour
GROUP BY 1
ORDER BY 2 DESC
"""

results = dune.execute(sql=sql, performance="medium")

for row in results.rows:
    print(f"{row['blockchain']}: ${row['volume']:,.2f}")

from dune_client import DuneClient
import pandas as pd

dune = DuneClient(api_key="YOUR_API_KEY")

# Get results as a pandas DataFrame
df = dune.execute_dataframe(query_id=3493826)

# Or convert manually
results = dune.execute(query_id=3493826)
df = pd.DataFrame(results.rows)

# Now use pandas for analysis
print(df.describe())
print(df.groupby('blockchain')['amount_usd'].sum())

Advanced Features

Filtering and Pagination

from dune_client import DuneClient

dune = DuneClient(api_key="YOUR_API_KEY")

# Use Dune's server-side filtering
results = dune.get_latest_result_dataframe(
    query=3493826,
    filters="amount_usd > 10000 AND blockchain = 'ethereum'",
    columns="tx_hash,amount_usd,block_time",
    sort_by="amount_usd desc",
    limit=100,
    offset=0
)

Query Management

from dune_client import DuneClient
from dune_client.query import QueryBase
from dune_client.types import QueryParameter

dune = DuneClient(api_key="YOUR_API_KEY")

# Create a new query
query = QueryBase(
    name="My DEX Analysis",
    query_sql="SELECT * FROM dex.trades WHERE blockchain = {{blockchain}}",
    params=[
        QueryParameter.text_type(name="blockchain", value="ethereum")
    ]
)

# Create the query on Dune
created_query = dune.create_query(query)
print(f"Created query: https://dune.com/queries/{created_query.query_id}")

# Update an existing query
query.query_id = created_query.query_id
query.query_sql = "SELECT * FROM dex.trades WHERE blockchain = {{blockchain}} LIMIT 1000"
dune.update_query(query)

# Execute it
results = dune.execute(query_id=created_query.query_id)

Data Uploads

from dune_client import DuneClient
import pandas as pd

dune = DuneClient(api_key="YOUR_API_KEY")

# Upload a CSV file
with open('data.csv', 'rb') as file:
    dune.upload_csv(
        data=file,
        table_name="my_dataset",
        description="Custom dataset for analysis"
    )

# Or upload a DataFrame
df = pd.DataFrame({
    'address': ['0x123...', '0x456...'],
    'label': ['DEX', 'Lending'],
    'category': ['DeFi', 'DeFi']
})

dune.upload_csv(
    data=df.to_csv(index=False),
    table_name="my_labels",
    is_private=False
)

API Reference

execute()

Execute a query and wait for results.Parameters:

query_id (int, optional): ID of saved query to execute
sql (str, optional): Raw SQL to execute
params (dict, optional): Query parameters
performance (str, optional): “medium” or “large” (default: “medium”)

Returns: ExecutionResult with .rows property

execute_dataframe()

Execute a query and return results as a pandas DataFrame.Parameters: Same as execute()Returns: pandas.DataFrame

get_latest_result()

Get the most recent execution results for a query without re-executing.Parameters:

query (int): Query ID
filters (str, optional): Server-side filters
columns (list, optional): Columns to include
sort_by (list, optional): Sort order
limit (int, optional): Max rows to return
offset (int, optional): Pagination offset

Returns: ExecutionResult

get_status()

Check execution status without fetching results.Parameters:

execution_id (str): Execution ID

Returns: ExecutionStatus

cancel_execution()

Cancel a running execution.Parameters:

execution_id (str): Execution ID

Returns: bool

Full Python SDK documentation →

TypeScript

The TypeScript SDK provides type-safe access to Dune’s API.

Installation

npm install @duneanalytics/client-sdk
# or
yarn add @duneanalytics/client-sdk

Quick Start

import { DuneClient, QueryParameter } from '@duneanalytics/client-sdk';

// Initialize client
const dune = new DuneClient(process.env.DUNE_API_KEY!);

// Execute a query
const results = await dune.execute({ queryId: 3493826 });

// Access results
console.log(`Got ${results.rows.length} rows`);
results.rows.forEach(row => console.log(row));

The execute() Function

import { DuneClient, QueryParameter } from '@duneanalytics/client-sdk';

const dune = new DuneClient(process.env.DUNE_API_KEY!);

// Execute a saved query with parameters
const results = await dune.execute({
  queryId: 3493826,
  parameters: [
    QueryParameter.text("blockchain", "ethereum"),
    QueryParameter.number("min_volume", 1000)
  ],
  performance: 'medium'
});

console.log(`Total rows: ${results.rows.length}`);

import { DuneClient } from '@duneanalytics/client-sdk';

const dune = new DuneClient(process.env.DUNE_API_KEY!);

// Execute arbitrary SQL
const sql = `
  SELECT 
    blockchain,
    SUM(amount_usd) as volume
  FROM dex.trades
  WHERE block_time > now() - interval '24' hour
  GROUP BY 1
  ORDER BY 2 DESC
`;

const results = await dune.execute({ sql, performance: 'medium' });

results.rows.forEach(row => {
  console.log(`${row.blockchain}: $${row.volume.toLocaleString()}`);
});

import { DuneClient } from '@duneanalytics/client-sdk';

const dune = new DuneClient(process.env.DUNE_API_KEY!);

// Get latest results with server-side filtering
const results = await dune.getLatestResults({
  queryId: 3493826,
  filters: "amount_usd > 10000 AND blockchain = 'ethereum'",
  columns: ["tx_hash", "amount_usd", "block_time"],
  sortBy: ["amount_usd desc"],
  limit: 100
});

console.log(results.rows);

Advanced Features

Type-Safe Query Parameters

import { DuneClient, QueryParameter } from '@duneanalytics/client-sdk';

const dune = new DuneClient(process.env.DUNE_API_KEY!);

const results = await dune.execute({
  queryId: 1215383,
  parameters: [
    QueryParameter.text("TextField", "Plain Text"),
    QueryParameter.number("NumberField", 3.1415926535),
    QueryParameter.date("DateField", "2022-05-04 00:00:00"),
    QueryParameter.enum("ListField", "Option 1"),
  ]
});

Async/Await Pattern

import { DuneClient } from '@duneanalytics/client-sdk';

const dune = new DuneClient(process.env.DUNE_API_KEY!);

async function fetchDEXMetrics() {
  try {
    // Execute multiple queries in parallel
    const [volume, users, protocols] = await Promise.all([
      dune.execute({ sql: "SELECT SUM(amount_usd) as total FROM dex.trades WHERE block_time > now() - interval '24' hour" }),
      dune.execute({ sql: "SELECT COUNT(DISTINCT trader) as total FROM dex.trades WHERE block_time > now() - interval '24' hour" }),
      dune.execute({ sql: "SELECT project, SUM(amount_usd) as volume FROM dex.trades WHERE block_time > now() - interval '24' hour GROUP BY 1" })
    ]);
    
    return {
      totalVolume: volume.rows[0].total,
      uniqueUsers: users.rows[0].total,
      topProtocols: protocols.rows
    };
  } catch (error) {
    console.error('Failed to fetch metrics:', error);
    throw error;
  }
}

// Use it
const metrics = await fetchDEXMetrics();
console.log(metrics);

API Reference

execute()

Execute a query and wait for results.Parameters:

queryId (number, optional): ID of saved query
sql (string, optional): Raw SQL to execute
parameters (QueryParameter[], optional): Query parameters
performance (“medium” | “large”, optional): Performance tier

Returns: Promise<ExecutionResult>

getLatestResults()

Get most recent results without re-executing.Parameters:

queryId (number): Query ID
filters (string, optional): Server-side filters
columns (string[], optional): Columns to include
sortBy (string[], optional): Sort order
limit (number, optional): Max rows

Returns: Promise<ResultsResponse>

getStatus()

Check execution status.Parameters:

executionId (string): Execution ID

Returns: Promise<ExecutionStatus>

cancelExecution()

Cancel a running execution.Parameters:

executionId (string): Execution ID

Returns: Promise<boolean>

Full TypeScript SDK documentation →

Go

The Go SDK provides idiomatic Go access to Dune’s API.

Installation

go get github.com/duneanalytics/duneapi-client-go

Quick Start

package main

import (
    "fmt"
    "os"
    
    "github.com/duneanalytics/duneapi-client-go"
)

func main() {
    // Initialize client
    client := duneapi.New(os.Getenv("DUNE_API_KEY"))
    
    // Execute a query
    results, err := client.Execute(3493826)
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Got %d rows\n", len(results.Rows))
}

The Execute() Function

package main

import (
    "fmt"
    "github.com/duneanalytics/duneapi-client-go"
)

func main() {
    client := duneapi.New("YOUR_API_KEY")
    
    // Execute a saved query
    results, err := client.ExecuteQuery(duneapi.ExecuteQueryParams{
        QueryID:     3493826,
        Performance: "medium",
        Parameters: map[string]interface{}{
            "blockchain": "ethereum",
            "min_volume": 1000,
        },
    })
    
    if err != nil {
        panic(err)
    }
    
    for _, row := range results.Rows {
        fmt.Printf("%+v\n", row)
    }
}

package main

import (
    "fmt"
    "github.com/duneanalytics/duneapi-client-go"
)

func main() {
    client := duneapi.New("YOUR_API_KEY")
    
    sql := `
        SELECT 
            blockchain,
            SUM(amount_usd) as volume
        FROM dex.trades
        WHERE block_time > now() - interval '24' hour
        GROUP BY 1
        ORDER BY 2 DESC
    `
    
    results, err := client.ExecuteSQL(duneapi.ExecuteSQLParams{
        SQL:         sql,
        Performance: "medium",
    })
    
    if err != nil {
        panic(err)
    }
    
    for _, row := range results.Rows {
        fmt.Printf("%s: $%.2f\n", row["blockchain"], row["volume"])
    }
}

package main

import (
    "context"
    "fmt"
    "time"
    
    "github.com/duneanalytics/duneapi-client-go"
)

func main() {
    client := duneapi.New("YOUR_API_KEY")
    
    // Create context with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()
    
    // Execute with context
    results, err := client.ExecuteWithContext(ctx, 3493826)
    if err != nil {
        if err == context.DeadlineExceeded {
            fmt.Println("Query timed out")
        } else {
            panic(err)
        }
        return
    }
    
    fmt.Printf("Got %d rows\n", len(results.Rows))
}

Advanced Features

Concurrent Queries

package main

import (
    "fmt"
    "sync"
    
    "github.com/duneanalytics/duneapi-client-go"
)

func main() {
    client := duneapi.New("YOUR_API_KEY")
    
    queries := []int{3493826, 3493827, 3493828}
    
    var wg sync.WaitGroup
    results := make([]duneapi.ExecutionResult, len(queries))
    
    for i, queryID := range queries {
        wg.Add(1)
        go func(index int, id int) {
            defer wg.Done()
            
            result, err := client.Execute(id)
            if err != nil {
                fmt.Printf("Error executing query %d: %v\n", id, err)
                return
            }
            
            results[index] = result
        }(i, queryID)
    }
    
    wg.Wait()
    
    for _, result := range results {
        fmt.Printf("Query completed with %d rows\n", len(result.Rows))
    }
}

Error Handling

package main

import (
    "errors"
    "fmt"
    
    "github.com/duneanalytics/duneapi-client-go"
)

func main() {
    client := duneapi.New("YOUR_API_KEY")
    
    results, err := client.Execute(3493826)
    if err != nil {
        // Handle different error types
        var apiErr *duneapi.APIError
        if errors.As(err, &apiErr) {
            fmt.Printf("API Error %d: %s\n", apiErr.StatusCode, apiErr.Message)
            return
        }
        
        var execErr *duneapi.ExecutionError
        if errors.As(err, &execErr) {
            fmt.Printf("Execution Error: %s\n", execErr.Message)
            return
        }
        
        // Unknown error
        panic(err)
    }
    
    fmt.Printf("Success! Got %d rows\n", len(results.Rows))
}

API Reference

Execute()

Execute a query and wait for results.Parameters:

queryID (int): Query ID to execute

Returns: (*ExecutionResult, error)

ExecuteQuery()

Execute a query with full options.Parameters:

params (ExecuteQueryParams): Struct with QueryID, Performance, Parameters

Returns: (*ExecutionResult, error)

ExecuteSQL()

Execute raw SQL.Parameters:

params (ExecuteSQLParams): Struct with SQL, Performance

Returns: (*ExecutionResult, error)

GetLatestResult()

Get most recent results without re-executing.Parameters:

queryID (int): Query ID
opts (*GetResultOptions): Optional filters, columns, sort

Returns: (*ResultsResponse, error)

GetStatus()

Check execution status.Parameters:

executionID (string): Execution ID

Returns: (*ExecutionStatus, error)

Full Go SDK documentation →

Comparison

Feature	Python	TypeScript	Go
execute() function	✅ Yes	✅ Yes	✅ Yes
Automatic polling	✅ Yes	✅ Yes	✅ Yes
Automatic pagination	✅ Yes	✅ Yes	✅ Yes
Server-side filtering	✅ Yes	✅ Yes	✅ Yes
Query management	✅ Full	⚠️ Partial	⚠️ Partial
Data uploads	✅ Full	❌ No	❌ No
DataFrame support	✅ Pandas	❌ No	❌ No
Type safety	⚠️ Optional	✅ Full	✅ Full
Async/await	⚠️ Limited	✅ Full	✅ Goroutines

Getting Help

Python Issues

Report Python SDK issues

TypeScript Issues

Report TypeScript SDK issues

Go Issues

Report Go SDK issues

Community Discord

Get help from the community

API Reference

View complete API documentation

​Python

​Installation

​Quick Start

​The execute() Function

​Advanced Features

​Filtering and Pagination

​Query Management

​Data Uploads

​API Reference

​TypeScript

​Installation

​Quick Start

​The execute() Function

​Advanced Features

​Type-Safe Query Parameters

​Async/Await Pattern

​API Reference

​Go

​Installation

​Quick Start

​The Execute() Function

​Advanced Features

​Concurrent Queries

​Error Handling

​API Reference

​Comparison

​Getting Help

Python Issues

TypeScript Issues

Go Issues

Community Discord

API Reference

Python

Installation

Quick Start

The execute() Function

Advanced Features

Filtering and Pagination

Query Management

Data Uploads

API Reference

TypeScript

Installation

Quick Start

The execute() Function

Advanced Features

Type-Safe Query Parameters

Async/Await Pattern

API Reference

Go

Installation

Quick Start

The Execute() Function

Advanced Features

Concurrent Queries

Error Handling

API Reference

Comparison

Getting Help