{"openapi":"3.1.0","info":{"title":"Dune (BYOK) API","version":"0.1.0","description":"Dune (BYOK) lets an AI assistant read your own Dune data through the Dune API with a key you supply (Dune API key). Read-only: 11 tools (get_latest_query_result, get_execution_result, get_execution_status, read_query, list_queries, list_datasets, get_dataset, search_datasets, search_datasets_by_contract, list_materialized_views, get_usage). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-dune.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-dune/docs"},"termsOfService":"https://connectorbay.com/byok-dune/terms"},"servers":[{"url":"https://byok-dune.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-dune/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_latest_query_result":{"post":{"operationId":"get_latest_query_result","summary":"Return the most recent stored result rows of a saved Dune query without running it. Credits are billed by result size; r","description":"Return the most recent stored result rows of a saved Dune query without running it. Credits are billed by result size; returns a not-found error if the query was edited since it last ran. Use for \"What are the latest results of Dune query 3493826\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query_id":{"description":"Numeric Dune query id, the number at the end of a query URL, for example 3493826.","minimum":1,"title":"Query Id","type":"integer"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows to return (1 to 1000). Reads are billed by result size, so keep this small.","title":"Limit"},"offset":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Row number to start from (0 is the first row), for paging.","title":"Offset"},"columns":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated column names to return; leave out for all columns. Fewer columns use fewer credits.","title":"Columns"},"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Row filter written like a SQL WHERE clause, for example 'amount_usd > 1000'.","title":"Filters"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Row order written like a SQL ORDER BY clause, for example 'block_time desc'.","title":"Sort By"}},"required":["query_id"],"title":"get_latest_query_resultArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_execution_result":{"post":{"operationId":"get_execution_result","summary":"Return result rows of a finished query execution by execution id, with paging, column selection, filter and sort. Credit","description":"Return result rows of a finished query execution by execution id, with paging, column selection, filter and sort. Credits are billed by result size. Use for \"Show the first rows of Dune execution 01HKZJ2683PHF9Q9PHHQ8FW4Q1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"execution_id":{"description":"Execution id returned when a query run was started, for example '01HKZJ2683PHF9Q9PHHQ8FW4Q1'.","maxLength":64,"title":"Execution Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows to return (1 to 1000). Reads are billed by result size, so keep this small.","title":"Limit"},"offset":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Row number to start from (0 is the first row), for paging.","title":"Offset"},"columns":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated column names to return; leave out for all columns. Fewer columns use fewer credits.","title":"Columns"},"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Row filter written like a SQL WHERE clause, for example 'amount_usd > 1000'.","title":"Filters"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Row order written like a SQL ORDER BY clause, for example 'block_time desc'.","title":"Sort By"}},"required":["execution_id"],"title":"get_execution_resultArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_execution_status":{"post":{"operationId":"get_execution_status","summary":"Show the state of a query execution (pending, executing, completed, failed), timing, queue position and credits used. Us","description":"Show the state of a query execution (pending, executing, completed, failed), timing, queue position and credits used. Use for \"Did Dune execution 01HKZJ2683PHF9Q9PHHQ8FW4Q1 finish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"execution_id":{"description":"Execution id returned when a query run was started, for example '01HKZJ2683PHF9Q9PHHQ8FW4Q1'.","maxLength":64,"title":"Execution Id","type":"string"}},"required":["execution_id"],"title":"get_execution_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/read_query":{"post":{"operationId":"read_query","summary":"Get a saved Dune query's name, description, owner, tags, SQL text, engine, version and parameter definitions. Use for \"S","description":"Get a saved Dune query's name, description, owner, tags, SQL text, engine, version and parameter definitions. Use for \"Show the SQL and parameters of Dune query 3493826\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query_id":{"description":"Numeric Dune query id, the number at the end of a query URL, for example 3493826.","minimum":1,"title":"Query Id","type":"integer"}},"required":["query_id"],"title":"read_queryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_queries":{"post":{"operationId":"list_queries","summary":"List queries owned by the key's account with id, name, description, tags and last update time. Use for \"Which Dune queri","description":"List queries owned by the key's account with id, name, description, tags and last update time. Use for \"Which Dune queries do I own\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many queries to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of queries to skip, for paging.","title":"Offset"}},"title":"list_queriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasets":{"post":{"operationId":"list_datasets","summary":"List datasets and tables available to the key, with type, owner and dates, optionally filtered by owner handle or type. ","description":"List datasets and tables available to the key, with type, owner and dates, optionally filtered by owner handle or type. Use for \"Which uploaded tables do I have on Dune\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many datasets to return (1 to 250).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of datasets to skip, for paging.","title":"Offset"},"owner_handle":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only datasets owned by this Dune handle.","title":"Owner Handle"},"type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated dataset types, for example 'uploaded_table,transformation_view'.","title":"Type"}},"title":"list_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dataset":{"post":{"operationId":"get_dataset","summary":"Get one dataset by slug, including its column names, types and nullability. Use for \"What columns does the dex.trades da","description":"Get one dataset by slug, including its column names, types and nullability. Use for \"What columns does the dex.trades dataset have on Dune\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Dataset slug as schema.table, for example 'dex.trades'.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_datasetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_datasets":{"post":{"operationId":"search_datasets","summary":"Search the Dune dataset catalog by free text such as 'dex trades' and return matching tables with category, chains and d","description":"Search the Dune dataset catalog by free text such as 'dex trades' and return matching tables with category, chains and description. Use for \"Find Dune tables about NFT trades\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Free-text search, for example 'dex trades' or 'ethereum transactions'.","maxLength":200,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Results to skip, for paging.","title":"Offset"}},"required":["query"],"title":"search_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_datasets_by_contract":{"post":{"operationId":"search_datasets_by_contract","summary":"Find Dune datasets that hold decoded data for a smart contract address, optionally on listed chains. Use for \"Which Dune","description":"Find Dune datasets that hold decoded data for a smart contract address, optionally on listed chains. Use for \"Which Dune tables cover contract 0x7a250d5630b4cf539739df2c5dacb4c659f2488d\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contract_address":{"description":"Contract address, for example 0x7a250d5630b4cf539739df2c5dacb4c659f2488d.","maxLength":100,"title":"Contract Address","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Results to skip, for paging.","title":"Offset"}},"required":["contract_address"],"title":"search_datasets_by_contractArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_materialized_views":{"post":{"operationId":"list_materialized_views","summary":"List the key account's materialized views with query id, size in bytes and privacy flag. Use for \"Which materialized vie","description":"List the key account's materialized views with query id, size in bytes and privacy flag. Use for \"Which materialized views do I have on Dune\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many views to return per page (up to 10000).","title":"Limit"},"offset":{"anyOf":[{"maximum":10000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Offset from the previous response's next_offset; leave out for the first page.","title":"Offset"}},"title":"list_materialized_viewsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_usage":{"post":{"operationId":"get_usage","summary":"Show credits used and included per billing period, storage bytes used and allowed, and private query and dashboard count","description":"Show credits used and included per billing period, storage bytes used and allowed, and private query and dashboard counts. Does not use credits. Use for \"How many Dune credits have I used this billing period\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Optional start of the period, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Optional end of the period, YYYY-MM-DD.","title":"End Date"}},"title":"get_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}