> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# TasksResource: Manage and Run Figranium Tasks
> Reference for the TasksResource in the Figranium Python SDK. Create, update, version, and execute tasks with typed requests and responses.
The `TasksResource` on the Figranium Python SDK is the primary way to manage tasks. Use it to list, create, update, version, and run tasks. Every method accepts an optional `options` keyword for per-request overrides such as custom headers or timeouts. The async client (`AsyncFigranium`) exposes the same resource and methods, so you can `await client.tasks.save(...)` or `await client.tasks.run(...)` with identical signatures.
```python theme={null}
import os
from figranium import Figranium
client = Figranium(api_key=os.environ["FIGRANIUM_API_KEY"])
```
The client-level convenience `client.run_task(id, input)` proxies directly to `client.tasks.run(id, input)`.
## Methods
Retrieve every task in the workspace.
* **HTTP endpoint:** `GET /api/tasks`
* **Signature:** `list(*, options=None) -> List[Task]`
```python list_tasks.py theme={null}
tasks = client.tasks.list()
print(len(tasks))
```
Returns a list of [`Task`](/docs/sdk/python/resources/tasks) objects.
Fetch a lightweight summary of all tasks.
* **HTTP endpoint:** `GET /api/tasks/list`
* **Signature:** `list_summaries(*, options=None) -> {"tasks": List[TaskSummary]}`
```python list_summaries.py theme={null}
result = client.tasks.list_summaries()
for t in result["tasks"]:
print(t["id"], t["name"])
```
Each `TaskSummary` contains `id`, `name`, and an optional `description`.
Create or update a task. Pass `create_version=True` to snapshot the current version before saving.
* **HTTP endpoint:** `POST /api/tasks` (with `?version=true` when `create_version` is set)
* **Signature:** `save(task, *, create_version=False, options=None) -> Task`
```python save_task.py theme={null}
from figranium import actions, variable, Task
task: Task = {
"name": "Search and extract",
"url": "https://example.com",
"mode": "agent",
"variables": {
"query": {"type": "string", "value": "figranium"},
},
"actions": [
actions.wait_for("#search"),
actions.type("#search", variable("query")),
actions.press("Enter", "#search"),
actions.get_content(".results", "resultText"),
],
}
saved = client.tasks.save(task, create_version=True)
print(saved["id"])
```
Returns the saved `Task`, including any server-generated `id`. For more about building actions, see [`Actions`](/docs/sdk/python/actions). For variable substitution, see [`Variables`](/docs/sdk/python/variables).
Refresh a task's `last_opened` timestamp without changing its definition.
* **HTTP endpoint:** `POST /api/tasks/{id}/touch`
* **Signature:** `touch(task_id, *, options=None) -> Task`
```python touch_task.py theme={null}
updated = client.tasks.touch("task_123")
```
Apply a partial patch to an existing task.
* **HTTP endpoint:** `PATCH /api/tasks/{id}`
* **Signature:** `update(task_id, patch, *, options=None) -> {"id": str, "updatedAt": int, "status": str, "task": Task}`
```python update_task.py theme={null}
result = client.tasks.update("task_123", {
"name": "Renamed task",
"wait": 2000,
})
print(result["updatedAt"])
```
Remove a task by ID.
* **HTTP endpoint:** `DELETE /api/tasks/{id}`
* **Signature:** `delete(task_id, *, options=None) -> {"id": str, "deleted": bool, "message": Optional[str]}`
```python delete_task.py theme={null}
result = client.tasks.delete("task_123")
print(result["deleted"], result.get("message"))
```
List all saved versions for a task.
* **HTTP endpoint:** `GET /api/tasks/{id}/versions`
* **Signature:** `versions(task_id, *, options=None) -> {"versions": List[TaskVersion]}`
```python list_versions.py theme={null}
result = client.tasks.versions("task_123")
for v in result["versions"]:
print(v["id"], v["timestamp"], v["name"])
```
Retrieve a specific version snapshot.
* **HTTP endpoint:** `GET /api/tasks/{id}/versions/{versionId}`
* **Signature:** `version(task_id, version_id, *, options=None) -> {"snapshot": Task, "metadata": {"id": str, "timestamp": int}}`
```python get_version.py theme={null}
result = client.tasks.version("task_123", "v_456")
print(result["metadata"]["timestamp"], result["snapshot"]["name"])
```
Delete all stored versions for a task.
* **HTTP endpoint:** `POST /api/tasks/{id}/versions/clear`
* **Signature:** `clear_versions(task_id, *, options=None) -> {"success": bool}`
```python clear_versions.py theme={null}
result = client.tasks.clear_versions("task_123")
```
Restore a task to a previous version snapshot.
* **HTTP endpoint:** `POST /api/tasks/{id}/rollback`
* **Signature:** `rollback(task_id, version_id, *, options=None) -> Task`
```python rollback_task.py theme={null}
restored = client.tasks.rollback("task_123", "v_456")
print(restored["id"])
```
Execute a task and return its result. This is the public execution endpoint, reachable at `/tasks/{id}/api`.
* **HTTP endpoint:** `POST /tasks/{id}/api`
* **Signature:** `run(task_id, input=None, *, options=None) -> ExecutionResult`
```python run_task.py theme={null}
result = client.tasks.run("task_123", {
"variables": {"query": "browser automation"},
})
print(result["data"])
```
The `input` object accepts `variables`, `taskVariables`, `webhookUrl`, and `runId`. For more about execution results and streaming, see [`ExecutionsResource`](/docs/sdk/python/resources/executions). To learn about task variables and runtime substitution, see [`Variables`](/docs/sdk/python/variables) and [`Actions`](/docs/sdk/python/actions). For per-request overrides, see [`RequestOptions`](/docs/sdk/python/request-options).