feat: add api to query devbox usage (#7296)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 112
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-b493cadf2e3b9658163a6bcf8f51e088dda169f12d68469c4441d17e889f5556.yml
-openapi_spec_hash: b27ec3822d88d10efa268f1681fddff3
-config_hash: 6c26299fd9ef01fb4713612a9a2ad17c
+configured_endpoints: 113
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/runloop-ai%2Frunloop-37187e72e61b850045924e6cb40207159ab794114add75a2bf36c87915326306.yml
+openapi_spec_hash: 33510c114bef0847855cdaf8f55c0774
+config_hash: 9f86425631c30497276e58b744dd3654

api.md

@@ -126,6 +126,7 @@ from runloop_api_client.types import (
     DevboxExecutionDetailView,
     DevboxKillExecutionRequest,
     DevboxListView,
+    DevboxResourceUsageView,
     DevboxSendStdInRequest,
     DevboxSendStdInResult,
     DevboxSnapshotListView,
@@ -158,6 +159,7 @@ Methods:
 - <code title="post /v1/devboxes/{id}/read_file_contents">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">read_file_contents</a>(id, \*\*<a href="src/runloop_api_client/types/devbox_read_file_contents_params.py">params</a>) -> str</code>
 - <code title="post /v1/devboxes/{id}/remove_tunnel">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">remove_tunnel</a>(id, \*\*<a href="src/runloop_api_client/types/devbox_remove_tunnel_params.py">params</a>) -> object</code>
 - <code title="post /v1/devboxes/{id}/resume">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">resume</a>(id) -> <a href="./src/runloop_api_client/types/devbox_view.py">DevboxView</a></code>
+- <code title="get /v1/devboxes/{id}/usage">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">retrieve_resource_usage</a>(id) -> <a href="./src/runloop_api_client/types/devbox_resource_usage_view.py">DevboxResourceUsageView</a></code>
 - <code title="post /v1/devboxes/{id}/shutdown">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">shutdown</a>(id) -> <a href="./src/runloop_api_client/types/devbox_view.py">DevboxView</a></code>
 - <code title="post /v1/devboxes/{id}/snapshot_disk">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">snapshot_disk</a>(id, \*\*<a href="src/runloop_api_client/types/devbox_snapshot_disk_params.py">params</a>) -> <a href="./src/runloop_api_client/types/devbox_snapshot_view.py">DevboxSnapshotView</a></code>
 - <code title="post /v1/devboxes/{id}/snapshot_disk_async">client.devboxes.<a href="./src/runloop_api_client/resources/devboxes/devboxes.py">snapshot_disk_async</a>(id, \*\*<a href="src/runloop_api_client/types/devbox_snapshot_disk_async_params.py">params</a>) -> <a href="./src/runloop_api_client/types/devbox_snapshot_view.py">DevboxSnapshotView</a></code>

src/runloop_api_client/resources/devboxes/devboxes.py

@@ -105,6 +105,7 @@
 from ...types.shared_params.mount import Mount
 from ...types.devbox_snapshot_view import DevboxSnapshotView
 from ...types.shared.launch_parameters import LaunchParameters as SharedLaunchParameters
+from ...types.devbox_resource_usage_view import DevboxResourceUsageView
 from ...types.devbox_execution_detail_view import DevboxExecutionDetailView
 from ...types.devbox_create_ssh_key_response import DevboxCreateSSHKeyResponse
 from ...types.shared_params.launch_parameters import LaunchParameters
@@ -1360,6 +1361,43 @@ def resume(
             cast_to=DevboxView,
         )
 
+    def retrieve_resource_usage(
+        self,
+        id: str,
+        *,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> DevboxResourceUsageView:
+        """Get resource usage metrics for a specific Devbox.
+
+        Returns CPU, memory, and disk
+        consumption calculated from the Devbox's lifecycle, excluding any suspended
+        periods for CPU and memory. Disk usage includes the full elapsed time since
+        storage is consumed even when suspended.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._get(
+            f"/v1/devboxes/{id}/usage",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DevboxResourceUsageView,
+        )
+
     def shutdown(
         self,
         id: str,
@@ -2972,6 +3010,43 @@ async def resume(
             cast_to=DevboxView,
         )
 
+    async def retrieve_resource_usage(
+        self,
+        id: str,
+        *,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> DevboxResourceUsageView:
+        """Get resource usage metrics for a specific Devbox.
+
+        Returns CPU, memory, and disk
+        consumption calculated from the Devbox's lifecycle, excluding any suspended
+        periods for CPU and memory. Disk usage includes the full elapsed time since
+        storage is consumed even when suspended.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return await self._get(
+            f"/v1/devboxes/{id}/usage",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=DevboxResourceUsageView,
+        )
+
     async def shutdown(
         self,
         id: str,
@@ -3426,6 +3501,9 @@ def __init__(self, devboxes: DevboxesResource) -> None:
         self.resume = to_raw_response_wrapper(
             devboxes.resume,
         )
+        self.retrieve_resource_usage = to_raw_response_wrapper(
+            devboxes.retrieve_resource_usage,
+        )
         self.shutdown = to_raw_response_wrapper(
             devboxes.shutdown,
         )
@@ -3531,6 +3609,9 @@ def __init__(self, devboxes: AsyncDevboxesResource) -> None:
         self.resume = async_to_raw_response_wrapper(
             devboxes.resume,
         )
+        self.retrieve_resource_usage = async_to_raw_response_wrapper(
+            devboxes.retrieve_resource_usage,
+        )
         self.shutdown = async_to_raw_response_wrapper(
             devboxes.shutdown,
         )
@@ -3636,6 +3717,9 @@ def __init__(self, devboxes: DevboxesResource) -> None:
         self.resume = to_streamed_response_wrapper(
             devboxes.resume,
         )
+        self.retrieve_resource_usage = to_streamed_response_wrapper(
+            devboxes.retrieve_resource_usage,
+        )
         self.shutdown = to_streamed_response_wrapper(
             devboxes.shutdown,
         )
@@ -3741,6 +3825,9 @@ def __init__(self, devboxes: AsyncDevboxesResource) -> None:
         self.resume = async_to_streamed_response_wrapper(
             devboxes.resume,
         )
+        self.retrieve_resource_usage = async_to_streamed_response_wrapper(
+            devboxes.retrieve_resource_usage,
+        )
         self.shutdown = async_to_streamed_response_wrapper(
             devboxes.shutdown,
         )

src/runloop_api_client/types/__init__.py

@@ -84,6 +84,7 @@
 from .benchmark_start_run_params import BenchmarkStartRunParams as BenchmarkStartRunParams
 from .blueprint_build_parameters import BlueprintBuildParameters as BlueprintBuildParameters
 from .devbox_execute_sync_params import DevboxExecuteSyncParams as DevboxExecuteSyncParams
+from .devbox_resource_usage_view import DevboxResourceUsageView as DevboxResourceUsageView
 from .gateway_config_list_params import GatewayConfigListParams as GatewayConfigListParams
 from .input_context_update_param import InputContextUpdateParam as InputContextUpdateParam
 from .network_policy_list_params import NetworkPolicyListParams as NetworkPolicyListParams

src/runloop_api_client/types/devbox_resource_usage_view.py

@@ -0,0 +1,48 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+
+from .._models import BaseModel
+
+__all__ = ["DevboxResourceUsageView"]
+
+
+class DevboxResourceUsageView(BaseModel):
+    id: str
+    """The devbox ID."""
+
+    disk_gb_seconds: int
+    """Disk usage in GB-seconds (total_elapsed_seconds multiplied by disk size in GB).
+
+    Disk is billed for elapsed time since storage is consumed even when suspended.
+    """
+
+    memory_gb_seconds: int
+    """Memory usage in GB-seconds (total_active_seconds multiplied by memory in GB)."""
+
+    start_time_ms: int
+    """The devbox creation time in milliseconds since epoch."""
+
+    status: str
+    """The current status of the devbox."""
+
+    total_active_seconds: int
+    """
+    Total time in seconds the devbox was actively running (excludes time spent
+    suspended).
+    """
+
+    total_elapsed_seconds: int
+    """
+    Total elapsed time in seconds from devbox creation to now (or end time if
+    terminated). Includes all time regardless of devbox state.
+    """
+
+    vcpu_seconds: int
+    """
+    vCPU usage in vCPU-seconds (total_active_seconds multiplied by the number of
+    vCPUs).
+    """
+
+    end_time_ms: Optional[int] = None
+    """The devbox end time in milliseconds since epoch, or null if still running."""

tests/api_resources/test_devboxes.py

@@ -17,6 +17,7 @@
     TunnelView,
     DevboxTunnelView,
     DevboxSnapshotView,
+    DevboxResourceUsageView,
     DevboxExecutionDetailView,
     DevboxCreateSSHKeyResponse,
     DevboxAsyncExecutionDetailView,
@@ -845,6 +846,44 @@ def test_path_params_resume(self, client: Runloop) -> None:
                 "",
             )
 
+    @parametrize
+    def test_method_retrieve_resource_usage(self, client: Runloop) -> None:
+        devbox = client.devboxes.retrieve_resource_usage(
+            "id",
+        )
+        assert_matches_type(DevboxResourceUsageView, devbox, path=["response"])
+
+    @parametrize
+    def test_raw_response_retrieve_resource_usage(self, client: Runloop) -> None:
+        response = client.devboxes.with_raw_response.retrieve_resource_usage(
+            "id",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        devbox = response.parse()
+        assert_matches_type(DevboxResourceUsageView, devbox, path=["response"])
+
+    @parametrize
+    def test_streaming_response_retrieve_resource_usage(self, client: Runloop) -> None:
+        with client.devboxes.with_streaming_response.retrieve_resource_usage(
+            "id",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            devbox = response.parse()
+            assert_matches_type(DevboxResourceUsageView, devbox, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @parametrize
+    def test_path_params_retrieve_resource_usage(self, client: Runloop) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
+            client.devboxes.with_raw_response.retrieve_resource_usage(
+                "",
+            )
+
     @parametrize
     def test_method_shutdown(self, client: Runloop) -> None:
         devbox = client.devboxes.shutdown(
@@ -2457,6 +2496,44 @@ async def test_path_params_resume(self, async_client: AsyncRunloop) -> None:
                 "",
             )
 
+    @parametrize
+    async def test_method_retrieve_resource_usage(self, async_client: AsyncRunloop) -> None:
+        devbox = await async_client.devboxes.retrieve_resource_usage(
+            "id",
+        )
+        assert_matches_type(DevboxResourceUsageView, devbox, path=["response"])
+
+    @parametrize
+    async def test_raw_response_retrieve_resource_usage(self, async_client: AsyncRunloop) -> None:
+        response = await async_client.devboxes.with_raw_response.retrieve_resource_usage(
+            "id",
+        )
+
+        assert response.is_closed is True
+        assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+        devbox = await response.parse()
+        assert_matches_type(DevboxResourceUsageView, devbox, path=["response"])
+
+    @parametrize
+    async def test_streaming_response_retrieve_resource_usage(self, async_client: AsyncRunloop) -> None:
+        async with async_client.devboxes.with_streaming_response.retrieve_resource_usage(
+            "id",
+        ) as response:
+            assert not response.is_closed
+            assert response.http_request.headers.get("X-Stainless-Lang") == "python"
+
+            devbox = await response.parse()
+            assert_matches_type(DevboxResourceUsageView, devbox, path=["response"])
+
+        assert cast(Any, response.is_closed) is True
+
+    @parametrize
+    async def test_path_params_retrieve_resource_usage(self, async_client: AsyncRunloop) -> None:
+        with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
+            await async_client.devboxes.with_raw_response.retrieve_resource_usage(
+                "",
+            )
+
     @parametrize
     async def test_method_shutdown(self, async_client: AsyncRunloop) -> None:
         devbox = await async_client.devboxes.shutdown(