Background Tasks

Spawn, monitor, and cancel long-running agent tasks.

Overview

Background tasks let you spawn long-running agent operations that execute asynchronously. Instead of waiting for a streaming response, you can create a task, check its status, and retrieve results when ready. Tasks are useful for batch operations, scheduled synthesis, or any workflow where you don't need real-time streaming.

For live progress on a running task (phase changes, progress %, messages), subscribe to GET /api/tasks/{task_id}/progress — see the Task Progress (SSE) page. The spawn/list/get/cancel routes on this page are the transactional control plane; the SSE endpoint is the streaming telemetry.

Spawn Task

POST /api/tasks/spawn

Create and start a new background agent task.

Request Body

Name	Type	Required	Description
`workspace_id`	UUID	Yes	Workspace ID
`conversation_id`	UUID	Yes	Conversation to log the task in
`task_type`	string	Yes	Type of task (e.g., `synthesis`, `recommendation`, `drafting`)
`prompt`	string	Yes	Instructions for the agent
`target_document_id`	UUID	No	Document to target (for drafting/block tasks)

Response (201 Created)

{
  "id": "b2c3d4e5-...",
  "workspace_id": "550e8400-...",
  "conversation_id": "a7b8c9d0-...",
  "task_type": "synthesis",
  "prompt": "Synthesize all interview sources from Q1",
  "status": "pending",
  "result_summary": null,
  "result_data": null,
  "error": null,
  "created_at": "2026-03-27T14:00:00Z",
  "started_at": null,
  "completed_at": null
}

List Tasks

GET /api/tasks

List background tasks for a workspace.

Query Parameters

Name	Type	Required	Description
`workspace_id`	UUID	Yes	Workspace ID
`status`	string	No	Filter by status: `pending`, `running`, `completed`, `failed`, `cancelled`
`limit`	integer	No	Max results (default: 20, max: 100)
`offset`	integer	No	Pagination offset (default: 0)

Response (200 OK)

{
  "tasks": [ ... ],
  "total": 5
}

Get Task

GET /api/tasks/{task_id}

Get a single task with its current status and results.

Response (200 OK)

{
  "id": "b2c3d4e5-...",
  "workspace_id": "550e8400-...",
  "task_type": "synthesis",
  "prompt": "Synthesize all interview sources from Q1",
  "status": "completed",
  "result_summary": "Extracted 12 insights across 5 themes",
  "result_data": {
    "insight_ids": ["uuid-1", "uuid-2"],
    "summary": "Key themes include..."
  },
  "error": null,
  "created_at": "2026-03-27T14:00:00Z",
  "started_at": "2026-03-27T14:00:02Z",
  "completed_at": "2026-03-27T14:00:45Z"
}

Cancel Task

POST /api/tasks/{task_id}/cancel

Cancel a pending or running task. Completed or failed tasks cannot be cancelled.

Response (200 OK)

Returns the task with status: "cancelled".

Task Status Flow

pending → running → completed
                  → failed
pending → cancelled
running → cancelled

Status	Description
`pending`	Task created, waiting to start
`running`	Agent is actively executing
`completed`	Finished successfully — check `result_summary` and `result_data`
`failed`	Execution failed — check `error` field
`cancelled`	Cancelled by user

Was this helpful?

PreviousExecution Tickets NextMissions