# Execute the calculate_square task with an input of 2
started_task_run = await client.workflows.run_task("calculate_square", [2])

task_run_id = started_task_run.id # ID is available immediately
task_run_status = started_task_run.status # Initial status is available immediately

finished_task_run = await started_task_run # Other properties become available after the task run completes
print(task_run.result) # Prints the task run's result (4)
```

| Argument | Description |
|--------|--------|
| `task_identifier` | **Required.** The **slug** indicating the task to run, available from your task's page in the [Render Dashboard][dboard]:  [img]  Always has the format `{workflow-slug}/{task-name}` (e.g., `my-workflow/calculate-square`). |
| `input_data` | **Required.** A list containing values for the task's [input arguments.](workflows-defining#task-arguments) For a task that takes zero arguments, provide an empty list, `[]`. |

###### `workflows.list_task_runs`

Lists task runs that match optional filters specified in the provided `ListTaskRunsParams` object.

**On success:** Returns a list of `TaskRun` objects.

**Raises:** [`ClientError`](#clienterror), [`ServerError`](#servererror), [`TimeoutError`](#timeouterror)

```python
from render_sdk.client.types import ListTaskRunsParams

params = ListTaskRunsParams(
  limit=10, # Return up to 10 runs
  cursor="cfQ74cE2sDI=", # Start from this cursor
  owners=["tea-d3jm7ai4d50c73fale60"] # Limit to these workspaces
)

await client.workflows.list_task_runs(params)
```

###### `workflows.get_task_run`

Retrieves the details of the task run with the specified ID.

**On success:** Returns a [`TaskRunDetails`](#the-taskrundetails-class) object.

**Raises:** [`ClientError`](#clienterror), [`ServerError`](#servererror), [`TimeoutError`](#timeouterror)

```python
await client.workflows.get_task_run("trn-abc123")
```

| Argument | Description |
|--------|--------|
| `task_run_id` | **Required.** The ID of the task run to retrieve. Has the format `trn-abc123...` |

###### `workflows.cancel_task_run`

Cancels the task run with the specified ID. This raises a [`ClientError`](#clienterror) if the task run is not found, or if it isn't currently running.

**On success:** Returns `None`.

**Raises:** [`ClientError`](#clienterror), [`ServerError`](#servererror), [`TimeoutError`](#timeouterror)

```python
await client.workflows.cancel_task_run("trn-abc123")
```

| Argument | Description |
|--------|--------|
| `task_run_id` | **Required.** The ID of the task run to cancel. Has the format `trn-abc123...` |

## The `AwaitableTaskRun` class

Represents the initial state of a task run as returned by the [`workflows.run_task`](#workflows-run-task) method.

You can `await` this object to wait for the task run to complete. On success, it returns a [`TaskRunDetails`](#the-taskrundetails-class) object:

```python
started_task_run = await client.workflows.run_task("calculate_square", [2])
finished_task_run = await started_task_run
```

**If the task run fails,** this `await` raises a [`TaskRunError`](#taskrunerror) exception.

### Properties

| Property | Description |
|--------|--------|
| `id` | The ID of the task run. Has the format `trn-abc123...` |
| `status` | The initial status of the task run. This is usually `pending`. |

</thead>

## The `TaskRunDetails` class

Represents the current state of a task run. Obtained in one of the following ways:

- `await`ing an [`AwaitableTaskRun`](#the-awaitabletaskrun-class) object returned by [`workflows.run_task`](#workflows-run-task):

  ```python
  started_task_run = await client.workflows.run_task("calculate_square", [2])
  finished_task_run = await started_task_run
  ```

- Calling the [`workflows.get_task_run`](#workflows-get-task-run) method:

  ```python
  task_run_details = await client.workflows.get_task_run("trn-abc123")
  ```

### Properties

| Property | Description |
|--------|--------|
| `id` | The ID of the task run. Has the format `trn-abc123...` |
| `task_id` | The ID of the run's associated task. Has the format `tsk-abc123...`. |
| `input_` | A list containing the argument values that were passed to the task run. Note the trailing underscore (`_`) in this property name. |
| `status` | The current status of the task run. One of the following: - `pending` - `running` - `completed` - `failed` - `canceled` |
| `results` | The task's return value. Present only if `status` is `completed`. |
| `parent_task_run_id` | The ID of the parent task run, if this task was called as a [subtask](workflows-defining#running-subtasks) by another task. For a root-level task, this value is `None`. |
| `root_task_run_id` | The ID of the root task run in this run's execution chain. For a root-level task, this value matches the value of `id`. |
| `retries` | The number of times the task run has retried. For runs that succeed without retries, this value is `0`. [Learn more about retries.](workflows-defining#retry-logic) |

## Exception types

Exceptions raised by the SDK have one of the types listed below. `RenderError` is the parent class for all other exception types.

```python
from render_sdk.client.errors import (
    RenderError, # Parent class for other exceptions
    ClientError,
    ServerError,
    TimeoutError,
    TaskRunError
)
```

| Exception | Description |
|--------|--------|
| `RenderError` | The base class for all exceptions raised by the SDK. |
| `ClientError` | Raised when a request to the Render API returns a 400-level error code. Common causes include: - Invalid API key - Invalid task identifier - Invalid task arguments - Invalid action (e.g., canceling a task run that is already completed) |
| `ServerError` | Raised when a request to the Render API returns a 500-level error code. |
| `TimeoutError` | Raised when a request to the Render API times out. |
| `TaskRunError` | Raised when an `await`ed task run fails. |