> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# update

> Patch a task's status, result, or payload extension.

`Tasks.aupdate` patches selected fields on a task. Pass only the fields you want to change: anything left as `None` is ignored.

For finer control over save semantics (especially when mutating `Task` attributes locally first), use `task.asave()` on the instance.

```python theme={"dark"}
from xpander_sdk import Tasks, AgentExecutionStatus

tasks = Tasks()
updated = await tasks.aupdate(
    task_id="task_xyz",
    status=AgentExecutionStatus.Completed,
    result="Final summary: …",
)
print(updated.status.value)
```

### Parameters

| Parameter                     | Type                   | Required | Description                                                     |
| ----------------------------- | ---------------------- | -------- | --------------------------------------------------------------- |
| `task_id`                     | `str`                  | Yes      | Task to update.                                                 |
| `tool_call_payload_extension` | `dict`                 | No       | Extra fields merged into every tool-call payload going forward. |
| `source`                      | `str`                  | No       | Update the origin tag.                                          |
| `status`                      | `AgentExecutionStatus` | No       | New status.                                                     |
| `last_executed_node_id`       | `str`                  | No       | Move the task's "current node" cursor (workflow agents).        |
| `result`                      | `str`                  | No       | Final result string.                                            |

Fields with value `None` are stripped from the request: only what you pass is sent.

### Returns `Task`

The freshly-loaded task with updates applied. See [`Task`](/developers/sdk-reference/tasks/task).

## Examples

### Mark complete

```python theme={"dark"}
await tasks.aupdate(
    task_id="task_xyz",
    status=AgentExecutionStatus.Completed,
    result="Done",
)
```

### Mark errored

```python theme={"dark"}
await tasks.aupdate(
    task_id="task_xyz",
    status=AgentExecutionStatus.Error,
    result="Connector failed: 503 Service Unavailable",
)
```

### Update only payload extension

```python theme={"dark"}
await tasks.aupdate(
    task_id="task_xyz",
    tool_call_payload_extension={"headers": {"X-Trace-ID": "abc-123"}},
)
```

This is rarely needed: payload extensions are usually set at task creation. Use this when you need to inject context after the task starts.

## Sync version

```python theme={"dark"}
tasks.update(task_id="task_xyz", status=AgentExecutionStatus.Completed)
```

## When to use this vs. `task.asave()`

| Use                                       | When                                                                                                                                                              |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tasks().aupdate(task_id=..., field=...)` | You only need to set a couple of fields and don't have a `Task` instance loaded.                                                                                  |
| `task.asave()`                            | You've mutated the `Task` instance directly (e.g. set `task.result = "..."`). `asave` PATCHes everything except `configuration` and (by default) `deep_planning`. |

The `@on_task` runtime auto-saves the task at the end of the handler: you don't usually call `aupdate` or `asave` yourself inside a handler.

## Errors

Raises [`ModuleException`](/developers/sdk-reference/error-handling). Common statuses:

| Status | Cause                                         |
| ------ | --------------------------------------------- |
| 404    | Task doesn't exist.                           |
| 409    | Concurrent update conflict. Reload and retry. |
| 500    | Server error.                                 |