Dune Getting Started: On-Chain Data Queries & API (2026)

Getting started overview

This guide provides the necessary steps to begin using Dune for on-chain data analysis and API access. It covers account creation, API key generation, and executing a foundational request. Dune is designed for querying and visualizing blockchain data using SQL, offering both a web interface for dashboards and an API for programmatic interaction with public and private data. The process typically involves signing up, understanding the platform's query environment, and then integrating through the API for more advanced use cases.

A quick reference for the initial setup is provided below:

Create an account and get keys

To begin using Dune, navigate to the Dune homepage and select the option to sign up. You can register using an email address and password, or through a linked Web3 wallet. Once registered, you will have access to the free tier, which allows creation of public dashboards and a limited number of private dashboards. For API access, a paid subscription, such as the Plus plan, is required, which starts at $399 per month, as detailed on the Dune pricing page. Paid tiers offer benefits like faster query execution and increased private dashboard limits.

After upgrading to a paid plan, your API key can be generated from your account settings. This key is essential for authenticating requests to the Dune API. Treat your API key as sensitive information; it provides access to your account's data and query capabilities. The API key is typically found in a dedicated 'API Keys' section within your user profile or settings dashboard. Ensure it is stored securely and not exposed in client-side code or public repositories.

Your first request

Dune's API allows programmatic interaction with its queries and dashboards. A common first request involves executing an existing query and fetching its results. This typically requires a query ID, which can be found in the URL of any public or private query on the Dune platform (e.g., dune.com/queries/{query_id}). The Dune API reference provides comprehensive details on specific endpoints and parameters for executing queries and retrieving results.

Example: Executing a public query via API

This example demonstrates how to use curl to execute a public query and then retrieve its results. Replace YOUR_API_KEY with your actual API key and YOUR_QUERY_ID with a valid Dune query ID.

Step 1: Execute the query

First, initiate the query execution. This call will return an execution ID.

curl -X POST \
  'https://api.dune.com/api/v1/query/YOUR_QUERY_ID/execute' \
  -H 'X-Dune-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{}'

Upon successful execution, the API will return a response similar to this, containing an execution_id:

{
  "execution_id": "01GZ187F17G2YF43R1C633R6P5"
}

Step 2: Check query status and fetch results

Use the execution_id from the previous step to check the status of the query and, once completed, fetch its results. You might need to poll this endpoint until the status indicates completion (e.g., 'query_state': 'completed').

curl -X GET \
  'https://api.dune.com/api/v1/query/01GZ187F17G2YF43R1C633R6P5/results' \
  -H 'X-Dune-Api-Key: YOUR_API_KEY'

The response will contain the query results, typically in a structured JSON format:

{
  "execution_id": "01GZ187F17G2YF43R1C633R6P5",
  "query_state": "completed",
  "result": {
    "rows": [
      {
        "block_number": 12345678,
        "transaction_count": 1500
      },
      {
        "block_number": 12345679,
        "transaction_count": 1650
      }
    ],
    "metadata": {
      "column_names": ["block_number", "transaction_count"],
      "row_count": 2
    }
  }
}

For detailed API endpoint specifications and additional parameters, refer to the Dune Query API documentation.

Common next steps

After successfully executing your first query, consider these next steps to deepen your interaction with Dune:

• Explore Dune SQL: Dune uses a variant of SQL for querying blockchain data. Familiarize yourself with its specific functions and table structures to write more complex and efficient queries. The Dune query basics documentation is a good starting point.
• Create and Share Dashboards: Organize your queries into dashboards for visualization and sharing. Dashboards can present data in various chart formats, making complex on-chain data more accessible.
• Utilize Advanced API Features: The Dune API offers more than just query execution. Explore endpoints for listing queries, fetching metadata, and managing private queries if your plan permits. Detailed information is available in the Dune API reference.
• Integrate with External Tools: Use the API to pull Dune data into other applications, BI tools, or custom data pipelines. For example, you might integrate Dune data into a Python script for further analysis or a web application for real-time display.
• Secure Your API Key: Implement robust security practices for your API key, such as using environment variables or a secrets manager, to prevent unauthorized access. The OAuth 2.0 framework, for example, defines a process for delegated authorization that can enhance security for API interactions (OAuth 2.0 specification).
• Monitor Query Performance: Pay attention to query execution times, especially for complex queries. Optimize your SQL queries to reduce resource consumption and improve performance, which can also impact your plan's usage limits.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• API Key Issues:
• Invalid Key: Double-check that your X-Dune-Api-Key header contains the correct, full API key. Keys are case-sensitive.
• Missing Key: Ensure the API key header is present in your request.
• Plan Restrictions: Confirm that your Dune account is on a paid plan that grants API access. The free tier does not include API access (Dune pricing details).
• Query ID Errors:
• Incorrect ID: Verify that the YOUR_QUERY_ID in the URL is a valid, existing query ID from the Dune platform.
• Private Query Access: If you are trying to access a private query, ensure your API key has the necessary permissions and your account is configured to access it.
• Network and Connectivity:
• Firewall/Proxy: Check if your network environment (firewall, corporate proxy) is blocking outgoing requests to api.dune.com.
• Internet Connection: Confirm you have an active internet connection.
• Rate Limiting:
• While unlikely on a first call, be aware that repeated, rapid requests can trigger rate limits. If you receive 429 Too Many Requests errors, slow down your request frequency. Information on API rate limits is typically found in the Dune API documentation.
• Understanding API Responses:
• HTTP Status Codes: Pay attention to the HTTP status code returned (e.g., 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error). These codes provide clues about the nature of the issue.
• Error Messages: The API response body often contains detailed error messages that can help diagnose the problem. Read them carefully.
• Documentation Review:
• If you are still stuck, revisit the Dune API reference and general Dune documentation for specific error codes or troubleshooting sections.