Add SQL execution and table listing features to Dune client

- Implemented `execute_sql` method in `ExecutionAPI` to allow direct SQL execution via the API.
- Updated `ExtendedAPI` to utilize the new SQL execution method for running queries.
- Added `list_tables` method in `TableAPI` to retrieve a paginated list of tables.
- Introduced `UsageResponse`, `TableInfo`, and `ListTablesResponse` models for handling API responses.
- Enhanced unit tests to cover new features and response parsing for usage and table information.

Author: 0xRobin

dune_client/api/execution.py

@@ -6,8 +6,10 @@
     get results: https://docs.dune.com/api-reference/executions/endpoint/get-execution-result
 """
 
+from __future__ import annotations
+
 from io import BytesIO
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from deprecated import deprecated
 
@@ -26,6 +28,9 @@
 )
 from dune_client.query import QueryBase  # noqa: TC001
 
+if TYPE_CHECKING:
+    from dune_client.types import QueryParameter
+
 
 class ExecutionAPI(BaseRouter):
     """
@@ -47,6 +52,41 @@ def execute_query(self, query: QueryBase, performance: str | None = None) -> Exe
         except KeyError as err:
             raise DuneError(response_json, "ExecutionResponse", err) from err
 
+    def execute_sql(
+        self,
+        query_sql: str,
+        params: list[QueryParameter] | None = None,
+        performance: str | None = None,
+    ) -> ExecutionResponse:
+        """
+        Execute arbitrary SQL directly via the API without creating a saved query.
+        https://docs.dune.com/api-reference/executions/endpoint/execute-query
+
+        Args:
+            query_sql: The SQL query string to execute
+            params: Optional list of query parameters
+            performance: Optional performance tier ("medium" or "large")
+
+        Returns:
+            ExecutionResponse with execution_id and state
+        """
+        payload: dict[str, Any] = {"query_sql": query_sql}
+
+        if params:
+            payload["query_parameters"] = {p.key: p.to_dict()["value"] for p in params}
+
+        payload["performance"] = performance or self.performance
+
+        self.logger.info(f"executing SQL on {performance or self.performance} cluster")
+        response_json = self._post(
+            route="/sql/execute",
+            params=payload,
+        )
+        try:
+            return ExecutionResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "ExecutionResponse", err) from err
+
     def cancel_execution(self, job_id: str) -> bool:
         """POST Execution Cancellation to Dune API for `job_id` (aka `execution_id`)"""
         response_json = self._post(

dune_client/api/extensions.py

@@ -19,6 +19,7 @@
 from dune_client.api.execution import ExecutionAPI
 from dune_client.api.query import QueryAPI
 from dune_client.api.table import TableAPI
+from dune_client.api.usage import UsageAPI
 from dune_client.models import (
     DuneError,
     ExecutionResultCSV,
@@ -38,7 +39,7 @@
 POLL_FREQUENCY_SECONDS = 1
 
 
-class ExtendedAPI(ExecutionAPI, QueryAPI, TableAPI, CustomEndpointAPI):
+class ExtendedAPI(ExecutionAPI, QueryAPI, TableAPI, UsageAPI, CustomEndpointAPI):
     """
     Provides higher level helper methods for faster
     and easier development on top of the base ExecutionAPI.
@@ -321,20 +322,49 @@ def run_sql(
         name: str = "API Query",
     ) -> ResultsResponse:
         """
-        Allows user to provide execute raw_sql via the CRUD interface
-        - create, run, get results with optional archive/delete.
-        - Query is by default made private and archived after execution.
+        Execute arbitrary SQL directly via the API and return results.
+        Uses the /sql/execute endpoint introduced in the Dune API.
+        https://docs.dune.com/api-reference/executions/endpoint/execute-query
+
+        Note: The `name`, `is_private`, and `archive_after` parameters are kept for
+        backward compatibility but are ignored when using the direct SQL execution endpoint.
+
+        Args:
+            query_sql: The SQL query string to execute
+            params: Optional list of query parameters
+            is_private: (Ignored) Kept for backward compatibility
+            archive_after: (Ignored) Kept for backward compatibility
+            performance: Optional performance tier ("medium" or "large")
+            ping_frequency: Seconds between status checks while polling
+            name: (Ignored) Kept for backward compatibility
+
+        Returns:
+            ResultsResponse with the query execution results
+
         Requires Plus subscription!
         """
-        query = self.create_query(name, query_sql, params, is_private)
-        try:
-            results = self.run_query(
-                query=query.base, performance=performance, ping_frequency=ping_frequency
-            )
-        finally:
-            if archive_after:
-                self.archive_query(query.base.query_id)
-        return results
+        # Execute SQL directly using the new endpoint
+        job_id = self.execute_sql(
+            query_sql=query_sql,
+            params=params,
+            performance=performance,
+        ).execution_id
+
+        # Poll for completion
+        status = self.get_execution_status(job_id)
+        while status.state not in ExecutionState.terminal_states():
+            self.logger.info(f"waiting for query execution {job_id} to complete: {status}")
+            time.sleep(ping_frequency)
+            status = self.get_execution_status(job_id)
+
+        if status.state == ExecutionState.FAILED:
+            self.logger.error(status)
+            raise QueryFailedError(f"Error data: {status.error}")
+
+        # Fetch and return results
+        return self._fetch_entire_result(
+            self.get_execution_results(job_id)
+        )
 
     ######################
     # Deprecated Functions

dune_client/api/table.py

@@ -14,6 +14,7 @@
     DeleteTableResult,
     DuneError,
     InsertTableResult,
+    ListTablesResponse,
 )
 
 
@@ -137,3 +138,34 @@ def delete_table(self, namespace: str, table_name: str) -> DeleteTableResult:
             return DeleteTableResult.from_dict(response_json)
         except KeyError as err:
             raise DuneError(response_json, "DeleteTableResult", err) from err
+
+    def list_tables(
+        self,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> ListTablesResponse:
+        """
+        https://docs.dune.com/api-reference/tables/endpoint/list
+        Get a paginated list of tables uploaded to Dune.
+
+        Args:
+            limit: Maximum number of tables to return (optional)
+            offset: Offset for pagination (optional)
+
+        Returns:
+            ListTablesResponse containing list of tables and pagination info
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        response_json = self._get(
+            route="/tables",
+            params=params if params else None,
+        )
+        try:
+            return ListTablesResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "ListTablesResponse", err) from err

dune_client/api/usage.py

@@ -0,0 +1,49 @@
+"""
+Usage API endpoints enable users to retrieve usage and billing information.
+https://docs.dune.com/api-reference/usage/endpoint/get-usage
+"""
+
+from __future__ import annotations
+
+from dune_client.api.base import BaseRouter
+from dune_client.models import DuneError, UsageResponse
+
+
+class UsageAPI(BaseRouter):
+    """
+    Implementation of Usage endpoints - Plus subscription only
+    https://docs.dune.com/api-reference/usage/
+    """
+
+    def get_usage(
+        self,
+        start_date: str,
+        end_date: str,
+    ) -> UsageResponse:
+        """
+        Get credits usage data, overage, number of private queries run, storage, etc.
+        over a specific timeframe.
+        https://docs.dune.com/api-reference/usage/endpoint/get-usage
+
+        Args:
+            start_date: Start date for the usage period (ISO format: YYYY-MM-DD)
+            end_date: End date for the usage period (ISO format: YYYY-MM-DD)
+
+        Returns:
+            UsageResponse containing usage statistics
+
+        Requires Plus subscription!
+        """
+        params = {
+            "start_date": start_date,
+            "end_date": end_date,
+        }
+        response_json = self._get(
+            route="/usage",
+            params=params,
+        )
+        try:
+            return UsageResponse.from_dict(response_json)
+        except KeyError as err:
+            raise DuneError(response_json, "UsageResponse", err) from err
+

dune_client/models.py

@@ -396,3 +396,68 @@ class ClearTableResult(DataClassJsonMixin):
     """
 
     message: str
+
+
+@dataclass
+class UsageResponse:
+    """
+    Representation of Response from Dune's [GET] Usage endpoint
+    https://docs.dune.com/api-reference/usage/endpoint/get-usage
+    """
+
+    credits_used: int
+    overage_credits: int
+    private_query_executions: int
+    storage_bytes: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> UsageResponse:
+        """Constructor from dictionary."""
+        return cls(
+            credits_used=int(data.get("credits_used", 0)),
+            overage_credits=int(data.get("overage_credits", 0)),
+            private_query_executions=int(data.get("private_query_executions", 0)),
+            storage_bytes=int(data.get("storage_bytes", 0)),
+        )
+
+
+@dataclass
+class TableInfo:
+    """Information about a single table"""
+
+    namespace: str
+    table_name: str
+    full_name: str
+    created_at: str
+    is_private: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TableInfo:
+        """Constructor from dictionary."""
+        return cls(
+            namespace=data["namespace"],
+            table_name=data["table_name"],
+            full_name=data["full_name"],
+            created_at=data["created_at"],
+            is_private=data["is_private"],
+        )
+
+
+@dataclass
+class ListTablesResponse:
+    """
+    Representation of Response from Dune's [GET] Tables List endpoint
+    https://docs.dune.com/api-reference/tables/endpoint/list
+    """
+
+    tables: list[TableInfo]
+    next_offset: int | None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ListTablesResponse:
+        """Constructor from dictionary."""
+        tables_data = data.get("tables", [])
+        return cls(
+            tables=[TableInfo.from_dict(table) for table in tables_data],
+            next_offset=data.get("next_offset"),
+        )

tests/e2e/test_client.py

@@ -385,6 +385,49 @@ def test_download_csv_success_with_params(self):
             }
         ]
 
+    def test_run_sql(self):
+        """Test the run_sql method that uses /sql/execute endpoint"""
+        dune = DuneClient()
+        query_sql = "select 85 as result"
+        results = dune.run_sql(query_sql)
+        assert results.get_rows() == [{"result": 85}]
+        # Note: With the new /sql/execute endpoint, no saved query is created,
+        # so this is purely an execution operation, not a CRUD operation.
+
+    @unittest.skip("Requires Plus subscription and valid data")
+    def test_get_usage(self):
+        """Test the get_usage endpoint"""
+        dune = DuneClient()
+        usage = dune.get_usage("2024-01-01", "2024-01-31")
+        # Verify response structure
+        assert hasattr(usage, "credits_used")
+        assert hasattr(usage, "overage_credits")
+        assert hasattr(usage, "private_query_executions")
+        assert hasattr(usage, "storage_bytes")
+        # All should be integers
+        assert isinstance(usage.credits_used, int)
+        assert isinstance(usage.overage_credits, int)
+        assert isinstance(usage.private_query_executions, int)
+        assert isinstance(usage.storage_bytes, int)
+
+    @unittest.skip("Requires Plus subscription and uploaded tables")
+    def test_list_tables(self):
+        """Test the list_tables endpoint"""
+        dune = DuneClient()
+        tables_response = dune.list_tables(limit=10)
+        # Verify response structure
+        assert hasattr(tables_response, "tables")
+        assert hasattr(tables_response, "next_offset")
+        assert isinstance(tables_response.tables, list)
+        # If there are tables, verify their structure
+        if len(tables_response.tables) > 0:
+            table = tables_response.tables[0]
+            assert hasattr(table, "namespace")
+            assert hasattr(table, "table_name")
+            assert hasattr(table, "full_name")
+            assert hasattr(table, "created_at")
+            assert hasattr(table, "is_private")
+
 
 @unittest.skip("This is an enterprise only endpoint that can no longer be tested.")
 class TestCRUDOps(unittest.TestCase):
@@ -421,17 +464,6 @@ def test_archive(self):
         assert self.client.archive_query(self.existing_query_id)
         assert not self.client.unarchive_query(self.existing_query_id)
 
-    @unittest.skip("Works fine, but creates too many queries!")
-    def test_run_sql(self):
-        query_sql = "select 85"
-        results = self.client.run_sql(query_sql)
-        assert results.get_rows() == [{"_col0": 85}]
-
-        # The default functionality is meant to create a private query and then archive it.
-        query = self.client.get_query(results.query_id)
-        assert query.meta.is_archived
-        assert query.meta.is_private
-
 
 if __name__ == "__main__":
     unittest.main()