Background Tasks

Signal API-worker run

Changed on

Sends a constrained control signal to the Temporal workflow. API-worker runs persist the signal as a durable run event and honor pause, resume, and update_context at cooperative runtime checkpoints between model steps.

post/v1/background-tasks/{slug}/runs/{runId}/signal

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /v1/background-tasks/{slug}/runs/{runId}/signal
  • Auth: HTTP bearer

Path parameters

slugstring required

Task slug.

Example:daily-summary

Background task slug, matching bg-tasks/<slug> locally.

runIdstring required

Run id.

Example:run-20260604-210000

Cloud-visible run id for a background task run.

Request body

payloadobject

Optional signal payload. update_context can carry context/text/requestedContext for the next runtime checkpoint.

signal'pause' | 'resume' | 'update_context' required

Supported control signal.

Example request

{
  "signal": "pause"
}

Response

Signal accepted.

attemptinteger

Attempt shown when this run is open.

completedAtstring date-time nullable

Desktop run completion timestamp.

createdAtstring date-time required

Server row creation timestamp.

errorstring nullable

Run error mirrored from the desktop.

errorCodestring nullable

Code shown before a failed run's reason.

executor'desktop' | 'api' required

Execution backend that owns this run.

idstring uuid required

Stable UUID primary key.

lastHeartbeatAtstring date-time nullable

Latest worker heartbeat/progress timestamp.

localRunIdstring nullable

Actual desktop run id once a queued remote trigger has been claimed and executed locally.

modelstring nullable

Desktop-facing LLM model id.

previousRunIdstring nullable

Previous run id when this run was created by retry.

progressMessagestring nullable

Human-readable progress message for polling clients.

progressPercentinteger nullable

Best-known run progress for polling clients, 0-100.

providerstring nullable

Provider slug. Depending on the row this may be an OAuth provider, LLM provider, or execution backend.

requestedContextstring nullable

Optional context supplied when a user remotely triggered the task.

revisioninteger required

Optimistic-lock revision used by write endpoints.

runIdstring required

Cloud-visible run id. Desktop-created runs can use local ids; remote triggers use remote-trigger-<uuid> until claimed.

slugstring required

Stable per-user background task slug matching bg-tasks/<slug> locally.

startedAtstring date-time nullable

Desktop run start timestamp.

status'queued' | 'running' | 'succeeded' | 'failed' | 'stopped' required

Background task run lifecycle state.

subUseCasestring nullable

Task-specific usage label for cost attribution.

summarystring nullable

Run summary mirrored from the desktop.

temporalClosedAtstring date-time nullable

Timestamp when Temporal execution closed.

temporalRunIdstring nullable

Temporal run id for the current workflow execution.

temporalStartedAtstring date-time nullable

Timestamp when Temporal execution started.

temporalStatusstring nullable

Last mirrored Temporal status, separate from the product status.

temporalWorkflowIdstring nullable

Temporal workflow id for API-worker runs.

trigger'manual' | 'cron' | 'window' | 'event' | 'retry' required

Trigger source for a task run.

updatedAtstring date-time required

Server row update timestamp.

useCasestring nullable

High-level usage label for cost attribution.

Example response

{
  "attempt": 1,
  "completedAt": "2026-06-04T21:02:00Z",
  "createdAt": "2026-06-04T21:00:30Z",
  "errorCode": "llm_call_failed",
  "executor": "api",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "lastHeartbeatAt": "2026-06-04T21:01:30Z",
  "localRunId": "local-run-42",
  "model": "openai/gpt-4.1-mini",
  "previousRunId": "run-20260604-205000",
  "progressMessage": "Building API-native task artifact.",
  "progressPercent": 50,
  "provider": "openai",
  "requestedContext": "Run this now and focus on high-risk accounts.",
  "revision": 2,
  "runId": "run-20260604-210000",
  "slug": "daily-summary",
  "startedAt": "2026-06-04T21:01:00Z",
  "status": "succeeded",
  "subUseCase": "daily-summary",
  "summary": "No high-priority account changes.",
  "temporalClosedAt": "2026-06-04T21:02:00Z",
  "temporalRunId": "00000000-0000-0000-0000-000000000001",
  "temporalStartedAt": "2026-06-04T21:01:00Z",
  "temporalStatus": "Running",
  "temporalWorkflowId": "background-task/user/daily-summary/api-trigger-123",
  "trigger": "manual",
  "updatedAt": "2026-06-04T21:02:05Z",
  "useCase": "background-task"
}

Changes