canonical: https://jentic.com/apis/dune.com/dune

# Dune Analytics API

The Dune Analytics API runs SQL-based analytics queries over on-chain data across multiple blockchains and returns the results programmatically. Agents can execute a saved query or raw SQL, poll the execution status, and retrieve results as JSON or CSV, as well as create, update, archive, and change the visibility of saved queries. Custom datasets can be uploaded by creating tables and inserting rows or replacing them from a CSV. Authentication uses a Dune API key sent in the X-Dune-Api-Key header.

## For AI agents

Execute SQL and saved queries against on-chain data, retrieve results as JSON or CSV, and upload custom datasets. Covers 21 operations across executions, queries, and tables.

## Scope

Does not handle on-chain transaction execution, wallet management, or token transfers. Use for on-chain analytics queries and dataset management only.

## Capabilities

- Execute saved queries or raw SQL against on-chain data across multiple blockchains
- Retrieve query execution results as JSON or CSV once an execution completes
- Poll execution status and cancel a running execution
- Create, update, archive, and toggle the privacy of saved queries
- Upload custom datasets by creating tables and inserting or replacing rows from a CSV
- Check API credit usage for your team

## Use cases

### AI Agent On-Chain Analytics

Let an AI agent answer blockchain data questions on demand: it executes a saved Dune query, polls the execution status until it completes, and retrieves the results as JSON for the agent to summarize. Through Jentic the agent discovers the right Dune operation by intent and calls it with the query id, so an analytics loop runs without a developer wiring the execute-poll-fetch sequence by hand.

Example prompt: Execute saved query 123456, poll its execution status until complete, then retrieve the results as JSON

### SQL Blockchain Data Queries

Analysts and agents run ad-hoc SQL directly against Dune's indexed on-chain datasets instead of maintaining their own node. The raw SQL execute operation returns an execution id, which you poll for status and then fetch results from as JSON or CSV. This supports one-off investigations and scheduled reporting over multiple chains.

Example prompt: Submit a raw SQL query that aggregates daily transaction counts for a contract, then fetch the execution results as CSV

### Custom Dataset Uploads

Teams enrich on-chain analysis with their own off-chain data by uploading it to Dune as tables. The API creates a table in your namespace, inserts rows or replaces the whole table from a CSV upload, and clears the data before the next load. Uploaded tables can then be joined in SQL queries alongside on-chain datasets.

Example prompt: Create a table in your namespace, upload a CSV to populate it, then clear the data before the next load

### Saved Query Management

Dashboards and recurring reports are backed by saved queries that need version control. The API creates a saved query, reads and updates its SQL, archives or unarchives it, and toggles whether it is private or public. Agents use this to maintain a library of queries without opening the Dune web editor.

Example prompt: Create a saved query, update its SQL, then make the query private

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/sql/execute` | Execute raw SQL |
| POST | `/v1/query/{query_id}/execute` | Execute a saved query |
| GET | `/v1/execution/{execution_id}/results` | Get execution results |
| GET | `/v1/execution/{execution_id}/status` | Get execution status |
| POST | `/v1/query` | Create a new saved query |
| POST | `/v1/table/create` | Create an uploaded table |
| POST | `/v1/table/upload/csv` | Upload CSV to create or replace a table |
| GET | `/v1/billing/usage` | Get API usage |

## Key resources

- **Executions** — Execute saved queries or raw SQL, poll status, cancel runs, and retrieve results as JSON or CSV
- **Queries** — Create, read, update, archive, and change the visibility of saved queries
- **Tables** — Create uploaded tables, insert or clear rows, upload CSVs, and delete tables
- **Usage** — Retrieve the team's current API credit usage

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 68 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 76 / 100
- **View full report:** https://jentic.com/apis/dune.com/dune/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Dune by hand means managing its X-Dune-Api-Key header, the execute-then-poll-then-fetch result flow, and CSV versus JSON result handling yourself. Through Jentic you install once, import Dune from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Dune carries the query id and table namespace in the URL path (`/v1/query/{query_id}`, `/v1/table/{namespace}/{table_name}`), so a rule can scope your agent to specific queries or tables and the operations you pick. You choose the operations it may call, so running queries and reading results can be allowed while deleting a table or clearing its data are not included unless you add them.
- **Credential handling:** Your Dune API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'execute an on-chain query' or 'upload a dataset', and Jentic returns the matching Dune operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bitquery GraphQL API** — On-chain data across multiple blockchains via GraphQL instead of SQL
- **GoldRush Multichain Data APIs** — Structured multichain balances, transactions, and token data via REST
- **The Graph Subgraph GraphQL API** — Query indexed subgraph data for specific protocols via GraphQL
- **CoinGecko API** — Off-chain token prices and market data to pair with on-chain queries

## FAQ

### What authentication does the Dune Analytics API use?

The Dune Analytics API authenticates with an API key sent in the X-Dune-Api-Key header per its OpenAPI spec. Keys are auto-generated for new teams and managed in account settings. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's context.

### Can I run raw SQL with the Dune Analytics API?

Yes. The SQL execute operation submits a raw SQL statement against Dune's on-chain datasets and returns an execution id, which you poll for status and then fetch results from as JSON or CSV. Saved queries work the same way through the saved-query execute operation.

### What are the rate limits for the Dune Analytics API?

The OpenAPI spec does not specify rate limits; see https://docs.dune.com/api-reference for current plan limits. You can track consumption with the billing usage operation, which returns your team's current API usage so an agent can stay within its credit allowance.

### Is there a Dune Analytics MCP server?

You don't need an MCP server to give your agent the Dune Analytics API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls operations like executing a query or uploading a dataset. Operations are discovered on demand, so no extra server's tool definitions sit in your agent's context.

### Can I limit what my agent is allowed to do with the Dune Analytics API?

Yes. Write a rule that allows only query execution and result retrieval, so the agent can run SQL and read results but cannot delete a table or clear its data. Because Dune addresses queries and tables by id in the URL path, a rule can also pin the agent to specific queries or tables, and every call it makes is logged.

### How do I execute an on-chain query with the Dune Analytics API through Jentic?

Search Jentic for 'execute an on-chain analytics query' to find the execute operation, run your saved query or raw SQL, then poll the execution status and fetch the results. To run it on your own infrastructure, install Jentic One from its GitHub repo.