render 1.0.1__tar.gz → 1.2.0__tar.gz

{render-1.0.1 → render-1.2.0}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [1.2.0] - 2026-09-23
+
+### Added
+
+- (Workflows) `start_task()` and `run_task()` accept a keyword-only `idempotency_key`, which makes starting a run safe to retry: repeating a call with the same key within 24 hours returns the run the first call started
+- (Workflows) `ctx.metadata` exposes `task_run_id`, `root_task_run_id` and `parent_task_run_id` for the running task. The IDs come from the task's initial input, so reading them does not make a network request; each is `None` when unavailable
+- (Sandboxes) Snapshot names: `snapshots.create()` accepts `name`, `sandboxes.create()` accepts `snapshot_name` to start from the snapshot that name resolves to, and `Snapshot` exposes `name`. Passing both `snapshot_id` and `snapshot_name` raises `ValueError`
+
+### Changed
+
+- Regenerated the REST client from the latest OpenAPI schema: blueprint creation, `include_previews` when listing build sources, and allowed domains on sandbox network policies. `Deploy` no longer has a `build_id` field
+
+## [1.1.0] - 2026-09-10
+
+### Added
+
+- (Sandboxes) `sandboxes.list_groups()`, async and sync, returning a `SandboxGroupList` of `SandboxGroup` snapshots and an optional `next_cursor`. Alpha guarantees at most one group per workspace, so the page holds zero or one group
+- (Sandboxes) Sandbox snapshots through `sandboxes.snapshots`, with `create`, `from_id`, `list` and `delete`, async and sync
+- (Sandboxes) Snapshot `kind` in `snapshots.create()`: `filesystem` captures the writable filesystem, `runtime` also captures memory and CPU state; optional `expires_at`
+- (Sandboxes) `sandboxes.create()` accepts `snapshot_id` to start from a snapshot instead of the base image
+- (Sandboxes) Snapshot error types `SnapshotNotFoundError`, `SnapshotNotReadyError` and `SnapshotPlanMismatchError`, each exposing the API error `code` when the API sends one
+- (Key Value) The size-based plan names (`256mb`, `1g`, `5g`, `10g`, `20g`, `40g`) are accepted as `InstanceConfiguration.plan` for automatic provisioning
+- `ClientError.code` carries the API error code when the response includes one
+
+### Fixed
+
+- (Blueprints) `ResourceRefType.WORKFLOW`, so `BlueprintDetail.from_dict` parses a blueprint that declares workflows instead of raising `ValueError`
+
+### Changed
+
+- Regenerated the REST client from the latest OpenAPI schema: the new compute plan identifiers, sandbox execution listing and retrieval, service disk usage events, and env group linking against artifact sources
+
+## [1.0.1] - 2026-08-21
+
+### Changed
+
+- **Breaking** The package is now named `render` rather than `render_sdk`; install `render` and import `render`. `render_sdk` remains on PyPI as a shim that re-exports `render` at the same version and warns on import
+
 ## [1.0.0] - 2026-08-20
 
 ### Changed

{render-1.0.1 → render-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: render
-Version: 1.0.1
+Version: 1.2.0
 Summary: Python SDK for Render Workflows
 Author-email: Render <support@render.com>
 License-File: LICENSE
@@ -102,6 +102,17 @@ from tasks_b import app as app_b
 combined = Workflows.from_workflows(app_a, app_b)
 ```
 
+### Task run IDs
+
+The task context exposes a read-only `ctx.metadata` object with
+`task_run_id`, `root_task_run_id`, and `parent_task_run_id` fields. The SDK reads
+them from the initial input response and keeps them for that execution, so
+accessing metadata does not make a network request.
+
+For a root run, `ctx.metadata.root_task_run_id` equals
+`ctx.metadata.task_run_id` and `ctx.metadata.parent_task_run_id` is `None`.
+IDs are `None` when unavailable.
+
 ### Running the Local Task Server
 
 For local development, use the Render CLI:
@@ -159,6 +170,19 @@ for event in render.workflows.task_run_events([task_run.id]):
 runs = render.workflows.list_task_runs(ListTaskRunsParams(limit=10))
 ```
 
+#### Idempotency Keys
+
+Pass an `idempotency_key` to make starting a run safe to retry. Repeating a call
+with the same key within 24 hours returns the run the first call started instead
+of starting another one, so a client that retries after a timeout does not run
+the task twice. Keys are scoped to a single workflow version.
+
+```python
+task_run = render.workflows.start_task(
+    "my-workflow/charge", [order_id], idempotency_key=f"charge-{order_id}"
+)
+```
+
 #### Async Usage
 
 For async contexts (e.g. FastAPI), use `RenderAsync`:

{render-1.0.1 → render-1.2.0}/README.md

@@ -77,6 +77,17 @@ from tasks_b import app as app_b
 combined = Workflows.from_workflows(app_a, app_b)
 ```
 
+### Task run IDs
+
+The task context exposes a read-only `ctx.metadata` object with
+`task_run_id`, `root_task_run_id`, and `parent_task_run_id` fields. The SDK reads
+them from the initial input response and keeps them for that execution, so
+accessing metadata does not make a network request.
+
+For a root run, `ctx.metadata.root_task_run_id` equals
+`ctx.metadata.task_run_id` and `ctx.metadata.parent_task_run_id` is `None`.
+IDs are `None` when unavailable.
+
 ### Running the Local Task Server
 
 For local development, use the Render CLI:
@@ -134,6 +145,19 @@ for event in render.workflows.task_run_events([task_run.id]):
 runs = render.workflows.list_task_runs(ListTaskRunsParams(limit=10))
 ```
 
+#### Idempotency Keys
+
+Pass an `idempotency_key` to make starting a run safe to retry. Repeating a call
+with the same key within 24 hours returns the run the first call started instead
+of starting another one, so a client that retries after a timeout does not run
+the task twice. Keys are scoped to a single workflow version.
+
+```python
+task_run = render.workflows.start_task(
+    "my-workflow/charge", [order_id], idempotency_key=f"charge-{order_id}"
+)
+```
+
 #### Async Usage
 
 For async contexts (e.g. FastAPI), use `RenderAsync`:

render-1.2.0/example/task/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)"
+    ]
+  }
+}

{render-1.0.1 → render-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "render"
-version = "1.0.1"
+version = "1.2.0"
 description = "Python SDK for Render Workflows"
 authors = [{ name = "Render", email = "support@render.com" }]
 readme = "README.md"

{render-1.0.1 → render-1.2.0}/render/__init__.py

@@ -33,7 +33,7 @@ Async REST API access:
     result = await task_run
 """
 
-__version__ = "1.0.1"
+__version__ = "1.2.0"
 
 # Render/RenderAsync are lazy-loaded so the workflow worker path stays fast.
 from typing import TYPE_CHECKING
@@ -42,6 +42,7 @@ from render.workflows import (
     Options,
     Retry,
     TaskContext,
+    TaskRunMetadata,
     Workflows,
     start,
     task,
@@ -58,6 +59,7 @@ __all__ = [
     "RenderAsync",  # Async REST API client
     "Workflows",  # Task definition
     "TaskContext",  # First parameter of every task
+    "TaskRunMetadata",
     # Configuration
     "Options",
     "Retry",

{render-1.0.1 → render-1.2.0}/render/client/errors.py

@@ -6,9 +6,14 @@ class RenderError(Exception):
 
 class ClientError(RenderError):
     """Exception for client errors. This is returned when
-    the client makes a request to the API and the API returns a 4xx error."""
+    the client makes a request to the API and the API returns a 4xx error.
 
-    pass
+    code is the machine-readable code from the error body, or None when the
+    API did not send one."""
+
+    def __init__(self, *args: object, code: str | None = None) -> None:
+        super().__init__(*args)
+        self.code = code
 
 
 class RateLimitError(ClientError):

{render-1.0.1 → render-1.2.0}/render/client/tests/test_client.py

@@ -77,28 +77,28 @@ def workflows_service(client):
 @pytest.fixture
 def mock_cancel_task_run_asyncio(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.cancel_task_run.asyncio_detailed"
+        "render.public_api.api.workflow_tasks.cancel_task_run.asyncio_detailed"
     )
 
 
 @pytest.fixture
 def mock_list_task_runs_asyncio(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.list_task_runs.asyncio_detailed"
+        "render.public_api.api.workflow_tasks.list_task_runs.asyncio_detailed"
     )
 
 
 @pytest.fixture
 def mock_create_task_asyncio(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.create_task.asyncio_detailed"
+        "render.public_api.api.workflow_tasks.create_task.asyncio_detailed"
     )
 
 
 @pytest.fixture
 def mock_get_task_run_asyncio(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.get_task_run.asyncio_detailed"
+        "render.public_api.api.workflow_tasks.get_task_run.asyncio_detailed"
     )
 
 
@@ -118,6 +118,62 @@ async def test_start_task_success(
     mock_create_task_asyncio.assert_called_once()
 
 
+@pytest.mark.asyncio
+async def test_start_task_omits_idempotency_key_when_not_given(
+    mock_create_task_asyncio, workflows_service, mock_task_run
+):
+    mock_create_task_asyncio.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    await workflows_service.start_task("test-task", {"input": "data"})
+
+    body = mock_create_task_asyncio.call_args.kwargs["body"]
+    assert "idempotencyKey" not in body.to_dict()
+
+
+@pytest.mark.asyncio
+async def test_start_task_sends_idempotency_key(
+    mock_create_task_asyncio, workflows_service, mock_task_run
+):
+    mock_create_task_asyncio.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    await workflows_service.start_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_asyncio.call_args.kwargs["body"]
+    assert body.to_dict()["idempotencyKey"] == "order-42"
+
+
+@pytest.mark.asyncio
+async def test_run_task_sends_idempotency_key(
+    mocker,
+    mock_create_task_asyncio,
+    workflows_service,
+    mock_task_run,
+    mock_task_run_details,
+):
+    mock_create_task_asyncio.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+    mocker.patch.object(
+        AwaitableTaskRun,
+        "_wait_for_completion",
+        new_callable=mocker.AsyncMock,
+        return_value=mock_task_run_details,
+    )
+
+    await workflows_service.run_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_asyncio.call_args.kwargs["body"]
+    assert body.idempotency_key == "order-42"
+
+
 @pytest.mark.asyncio
 async def test_start_task_failure(mock_create_task_asyncio, workflows_service):
     """Test task start failure."""

{render-1.0.1 → render-1.2.0}/render/client/tests/test_method_parity.py

@@ -25,8 +25,11 @@ from render.experimental.object.client_sync import (
 )
 from render.experimental.sandbox.api import SandboxApi
 from render.experimental.sandbox.api_sync import SyncSandboxApi
-from render.experimental.sandbox.client import SandboxClient
-from render.experimental.sandbox.client_sync import SyncSandboxClient
+from render.experimental.sandbox.client import SandboxClient, SnapshotClient
+from render.experimental.sandbox.client_sync import (
+    SyncSandboxClient,
+    SyncSnapshotClient,
+)
 
 # All async/sync class pairs. Add new pairs here when creating a new service.
 ASYNC_SYNC_PAIRS = [
@@ -38,6 +41,7 @@ ASYNC_SYNC_PAIRS = [
     (ScopedObjectClient, SyncScopedObjectClient),
     (SandboxApi, SyncSandboxApi),
     (SandboxClient, SyncSandboxClient),
+    (SnapshotClient, SyncSnapshotClient),
 ]
 
 # Modules that contain async service classes. If you add a new module with

{render-1.0.1 → render-1.2.0}/render/client/tests/test_util.py

@@ -10,6 +10,7 @@ from render.client.util import (
     handle_http_error,
     handle_httpx_exception,
     handle_storage_http_error,
+    request_errors,
     retry_with_backoff,
 )
 from render.public_api.models.error import Error
@@ -159,6 +160,51 @@ def test_handle_api_error_extracts_message_from_content_when_parsed_is_none():
         handle_api_error(response, "API request")
 
 
+def test_handle_api_error_sets_code_from_parsed_error():
+    response = Response(
+        status_code=409,
+        content=b"",
+        headers={},
+        parsed=Error(message="sandbox is suspended", code="sandbox_not_running"),
+    )
+    with pytest.raises(ClientError, match="sandbox is suspended") as excinfo:
+        handle_api_error(response, "create snapshot")
+    assert excinfo.value.code == "sandbox_not_running"
+
+
+def test_handle_api_error_sets_code_from_content_when_parsed_is_none():
+    response = Response(
+        status_code=409,
+        content=b'{"message": "still creating", "code": "snapshot_creating"}',
+        headers={},
+        parsed=None,
+    )
+    with pytest.raises(ClientError) as excinfo:
+        handle_api_error(response, "delete snapshot")
+    assert excinfo.value.code == "snapshot_creating"
+
+
+def test_handle_api_error_code_is_none_when_absent():
+    response = Response(
+        status_code=400, content=b"", headers={}, parsed=Error(message="Bad request")
+    )
+    with pytest.raises(ClientError) as excinfo:
+        handle_api_error(response, "API request")
+    assert excinfo.value.code is None
+
+
+def test_handle_api_error_ignores_non_string_code_in_content():
+    response = Response(
+        status_code=409,
+        content=b'{"message": "still creating", "code": 409}',
+        headers={},
+        parsed=None,
+    )
+    with pytest.raises(ClientError) as excinfo:
+        handle_api_error(response, "delete snapshot")
+    assert excinfo.value.code is None
+
+
 def test_handle_api_error_fallback_when_content_is_not_json():
     """When parsed is None and content is not JSON, should use fallback message."""
     response = Response(
@@ -206,6 +252,32 @@ def test_handle_wrapper_exception_unexpected_error():
         _handle_wrapper_exception(exc, "op")
 
 
+def test_request_errors_passes_through_when_nothing_is_raised():
+    with request_errors("op"):
+        pass
+
+
+def test_request_errors_reraises_render_error():
+    with (
+        pytest.raises(ClientError, match="already a render error"),
+        request_errors("op"),
+    ):
+        raise ClientError("already a render error")
+
+
+def test_request_errors_translates_httpx_request_error():
+    with pytest.raises(TimeoutError, match="op timed out"), request_errors("op"):
+        raise httpx.TimeoutException("timed out")
+
+
+def test_request_errors_wraps_unexpected_error():
+    with (
+        pytest.raises(RenderError, match="failed with unexpected error: boom"),
+        request_errors("op"),
+    ):
+        raise ValueError("boom")
+
+
 class TestHandleStorageHttpError:
     """Tests for handle_storage_http_error function."""
 

{render-1.0.1 → render-1.2.0}/render/client/tests/test_workflows_sync.py

@@ -77,28 +77,28 @@ def sync_workflows_service(client):
 @pytest.fixture
 def mock_cancel_task_run_sync(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.cancel_task_run.sync_detailed"
+        "render.public_api.api.workflow_tasks.cancel_task_run.sync_detailed"
     )
 
 
 @pytest.fixture
 def mock_list_task_runs_sync(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.list_task_runs.sync_detailed"
+        "render.public_api.api.workflow_tasks.list_task_runs.sync_detailed"
     )
 
 
 @pytest.fixture
 def mock_create_task_sync(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.create_task.sync_detailed"
+        "render.public_api.api.workflow_tasks.create_task.sync_detailed"
     )
 
 
 @pytest.fixture
 def mock_get_task_run_sync(mocker):
     return mocker.patch(
-        "render.public_api.api.workflow_tasks_beta.get_task_run.sync_detailed"
+        "render.public_api.api.workflow_tasks.get_task_run.sync_detailed"
     )
 
 
@@ -117,6 +117,58 @@ def test_start_task_success(
     mock_create_task_sync.assert_called_once()
 
 
+def test_start_task_omits_idempotency_key_when_not_given(
+    mock_create_task_sync, sync_workflows_service, mock_task_run
+):
+    mock_create_task_sync.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    sync_workflows_service.start_task("test-task", {"input": "data"})
+
+    body = mock_create_task_sync.call_args.kwargs["body"]
+    assert "idempotencyKey" not in body.to_dict()
+
+
+def test_start_task_sends_idempotency_key(
+    mock_create_task_sync, sync_workflows_service, mock_task_run
+):
+    mock_create_task_sync.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+
+    sync_workflows_service.start_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_sync.call_args.kwargs["body"]
+    assert body.to_dict()["idempotencyKey"] == "order-42"
+
+
+def test_run_task_sends_idempotency_key(
+    mocker,
+    mock_create_task_sync,
+    sync_workflows_service,
+    mock_task_run,
+    mock_task_run_details,
+):
+    mock_create_task_sync.return_value = Response(
+        status_code=202, content=b"", headers={}, parsed=mock_task_run
+    )
+    mocker.patch.object(
+        sync_workflows_service,
+        "_task_run_completed_with_sse",
+        return_value=mock_task_run_details,
+    )
+
+    sync_workflows_service.run_task(
+        "test-task", {"input": "data"}, idempotency_key="order-42"
+    )
+
+    body = mock_create_task_sync.call_args.kwargs["body"]
+    assert body.idempotency_key == "order-42"
+
+
 def test_start_task_failure(mock_create_task_sync, sync_workflows_service):
     """Test task start failure."""
 

{render-1.0.1 → render-1.2.0}/render/client/util.py

@@ -4,7 +4,8 @@ import functools
 import json
 import logging
 from asyncio import sleep
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Generator
+from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, NoReturn
 
 import httpx
@@ -194,6 +195,7 @@ def handle_api_error(
 
     message: str | None = None
     error_id: str | None = None
+    code: str | None = None
 
     # Try to extract error info from parsed response
     if isinstance(response.parsed, Error):
@@ -203,6 +205,9 @@ def handle_api_error(
         raw_id = getattr(response.parsed, "id", None)
         if raw_id is not None and not isinstance(raw_id, Unset):
             error_id = raw_id
+        raw_code = getattr(response.parsed, "code", None)
+        if raw_code is not None and not isinstance(raw_code, Unset):
+            code = raw_code
     elif response.parsed is None and response.content:
         # Parsed is None (e.g., 400 not handled) - try to extract from raw content
         try:
@@ -210,6 +215,8 @@ def handle_api_error(
             if isinstance(error_data, dict):
                 message = error_data.get("message")
                 error_id = error_data.get("id")
+                raw_code = error_data.get("code")
+                code = raw_code if isinstance(raw_code, str) else None
         except (json.JSONDecodeError, UnicodeDecodeError):
             pass
 
@@ -225,13 +232,13 @@ def handle_api_error(
 
     if response.status_code:
         if response.status_code == 429:
-            raise RateLimitError(full_message)
+            raise RateLimitError(full_message, code=code)
         if response.status_code >= 400 and response.status_code < 500:
-            raise ClientError(full_message)
+            raise ClientError(full_message, code=code)
         elif response.status_code >= 500:
             raise ServerError(full_message)
     else:
-        raise ClientError(full_message)
+        raise ClientError(full_message, code=code)
 
 
 def _handle_wrapper_exception(exc: Exception, operation: str) -> NoReturn:
@@ -252,6 +259,21 @@ def _handle_wrapper_exception(exc: Exception, operation: str) -> NoReturn:
     raise RenderError(f"{operation} failed with unexpected error: {exc}") from exc
 
 
+@contextmanager
+def request_errors(operation: str) -> Generator[None, None, None]:
+    """
+    Context manager form of handle_http_errors for a single request.
+
+    Translates HTTPX exceptions and non-JSON responses raised inside the block
+    into custom exceptions. Unlike the decorator, it leaves the HTTP status of
+    the response to the caller.
+    """
+    try:
+        yield
+    except Exception as exc:
+        _handle_wrapper_exception(exc, operation)
+
+
 def handle_http_errors(operation: str):
     """
     Decorator that handles HTTPX exceptions and HTTP error responses.

{render-1.0.1 → render-1.2.0}/render/client/util_sync.py

@@ -16,6 +16,7 @@ from render.client.util import (
     handle_http_error,
     handle_httpx_exception,
     handle_storage_http_error,
+    request_errors,
 )
 from render.public_api.models.error import Error
 from render.public_api.types import Response
@@ -28,6 +29,7 @@ __all__ = [
     "handle_api_error",
     "handle_http_error",
     "handle_httpx_exception",
+    "request_errors",
     "handle_storage_http_error",
 ]
 

{render-1.0.1 → render-1.2.0}/render/client/workflows.py

@@ -24,13 +24,13 @@ from render.client.util import (
     handle_httpx_exception,
     retry_with_backoff,
 )
-from render.public_api.api.workflow_tasks_beta import (
+from render.public_api.api.workflow_tasks import (
     cancel_task_run,
     create_task,
     get_task_run,
     list_task_runs,
 )
-from render.public_api.api.workflow_tasks_beta.stream_task_runs_events import (
+from render.public_api.api.workflow_tasks.stream_task_runs_events import (
     _get_kwargs,
 )
 from render.public_api.models.error import Error
@@ -184,6 +184,8 @@ class WorkflowsService:
         self,
         task_slug: TaskSlug,
         input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> AwaitableTaskRun:
         """Start a task and return an awaitable task run without waiting for completion.
 
@@ -203,6 +205,9 @@ class WorkflowsService:
             input_data: The input data for the task. Can be either:
                 - A list for positional arguments: [arg1, arg2, arg3]
                 - A dict for named parameters: {"param1": value1, "param2": value2}
+            idempotency_key: Optional client-generated key that makes this call safe
+                to retry. Repeating a call with the same key within 24 hours returns
+                the task run the first call started instead of starting another one.
 
         Returns:
             AwaitableTaskRun: A task run that can be awaited for the result
@@ -212,7 +217,11 @@ class WorkflowsService:
             ServerError: For 5xx server errors and network failures
             TimeoutError: If the request times out
         """
-        response = (await self._create_task_api_call(task_slug, input_data)).parsed
+        response = (
+            await self._create_task_api_call(
+                task_slug, input_data, idempotency_key=idempotency_key
+            )
+        ).parsed
 
         return AwaitableTaskRun(response, self)
 
@@ -220,6 +229,8 @@ class WorkflowsService:
         self,
         task_slug: TaskSlug,
         input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> TaskRunDetails:
         """Start a task and wait for it to complete, returning the result.
 
@@ -231,6 +242,9 @@ class WorkflowsService:
             input_data: The input data for the task. Can be either:
                 - A list for positional arguments: [arg1, arg2, arg3]
                 - A dict for named parameters: {"param1": value1, "param2": value2}
+            idempotency_key: Optional client-generated key that makes this call safe
+                to retry. Repeating a call with the same key within 24 hours returns
+                the task run the first call started instead of starting another one.
 
         Returns:
             TaskRunDetails: The completed task run details
@@ -241,12 +255,18 @@ class WorkflowsService:
             TimeoutError: If the request times out
             TaskRunError: If the task run fails with an error
         """
-        task_run = await self.start_task(task_slug, input_data)
+        task_run = await self.start_task(
+            task_slug, input_data, idempotency_key=idempotency_key
+        )
         return await task_run
 
     @handle_http_errors("create task")
     async def _create_task_api_call(
-        self, task_slug: TaskSlug, input_data: TaskData
+        self,
+        task_slug: TaskSlug,
+        input_data: TaskData,
+        *,
+        idempotency_key: str | None = None,
     ) -> Response[Error | TaskRun]:
         """Internal method to make the create task API call."""
         # Convert dict to TaskDataType1 for named parameters
@@ -260,6 +280,7 @@ class WorkflowsService:
         run_task = RunTask(
             task=task_slug,
             input_=task_data_input,
+            idempotency_key=idempotency_key if idempotency_key is not None else UNSET,
         )
 
         # Make the API call