Skip to main content

​
Retrieve Task

Get a task by ID. 
task = client.tasks.retrieve(
    task_id="task-uuid",
    relationships=["messages", "state"],
)
Parameters:
  • task_id (str): Task UUID
  • relationships (list, optional): Include related data
Returns: TaskResponse

​
List Tasks

List tasks for an agent. 
tasks = client.tasks.list(
    agent_id="agent-id",
    limit=20,
    page_number=1,
)
Parameters:
  • agent_id (str, optional): Filter by agent
  • agent_name (str, optional): Filter by agent name
  • limit (int, optional): Max results
  • page_number (int, optional): Page number
  • order_by (str, optional): Sort field
  • order_direction (str, optional): “asc” or “desc”
Returns: TaskListResponse

​
Update Task

Update task metadata. 
task = client.tasks.update(
    task_id="task-uuid",
    task_metadata={"status": "in_progress"},
)
Parameters:
  • task_id (str): Task UUID
  • task_metadata (dict): Metadata to update
Returns: Task

​
Delete Task

Delete a task. 
client.tasks.delete("task-uuid")
Parameters:
  • task_id (str): Task UUID
Returns: DeleteResponse

​
Migrate Tasks

Migrate tasks to a new version. 
result = client.tasks.migrate(
    task_ids=["task-1", "task-2"],
    target_version_id="version-123",
)
Parameters:
  • task_ids (list): Task UUIDs to migrate
  • target_version_id (str): Target version
Returns: MigrateTasksResponse

​
System Folder Operations

​
Get System Folder

folder = client.tasks.get_system_folder(
    task_id="task-uuid",
    folder_type="dot_claude",
)

​
Get Upload URL

url_info = client.tasks.get_system_folder_upload_url(
    task_id="task-uuid",
    folder_type="dot_claude",
)
# Upload to url_info.url

​
Sync Complete

client.tasks.system_folder_sync_complete(
    task_id="task-uuid",
    folder_type="dot_claude",
)

​
Task Model

task.id           # Task UUID
task.name         # Optional name
task.status       # Status (RUNNING, COMPLETED, etc.)
task.agent_id     # Associated agent
task.version_id   # Running version
task.created_at   # Creation timestamp
task.updated_at   # Last update