Skip to main content

​
Endpoint

POST http://localhost:8080/api/v1/tasks/{id}/pause

​
Description

Pauses a running task at the next workflow checkpoint. The current activity (LLM call, tool, etc.) is allowed to finish, and then the workflow blocks until it is resumed or cancelled. Use this when you want to temporarily stop long‑running research or supervisor workflows without losing progress.

​
Authentication

Required: Yes Include API key in header: 
X-API-Key: sk_test_123456

​
Request

​
Headers

HeaderRequiredDescription
X-API-KeyYesAPI authentication key
Content-TypeNoapplication/json if body
traceparentNoW3C trace context

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesTask ID (Temporal workflow ID)

​
Body Parameters

ParameterTypeRequiredDescription
reasonstringNoOptional pause reason note

​
Request Body Example

{
  "reason": "Pause while user reviews intermediate results"
}

​
Response

​
202 Accepted

{
  "success": true,
  "message": "Pause signal sent",
  "task_id": "task-123"
}

​
404 Not Found

{ "error": "Task not found" }

​
409 Failed Precondition

Cannot pause task in invalid state: 
{ "error": "cannot pause completed task" }

{ "error": "cannot pause failed task" }

{ "error": "cannot pause cancelled task" }

{ "error": "cannot pause timed out task" }

{ "error": "task is already paused" }

​
401 / 403

{ "error": "Unauthorized" }
or 
{ "error": "Forbidden" }

​
Notes

  • Pause takes effect at well‑defined checkpoints (e.g., pre_execution, pre_completion); it does not interrupt in‑flight activities.
  • While paused, SSE streams will emit workflow.pausing and workflow.paused events with a checkpoint field.
  • Ownership and tenancy are enforced: users can only pause their own tasks.