Sign in
Background Tasks

Patch task run mirror

Changed on

Updates run state with optimistic locking. Desktop should patch queued remote-trigger runs to running/succeeded/failed as it claims and completes them locally.

patch/v1/background-tasks/{slug}/runs/{runId}

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}
  • 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

completedAtstring date-time nullable

Run completion timestamp.

errorstring nullable

Latest run error.

executor'desktop' | 'api'

Execution backend.

lastHeartbeatAtstring date-time nullable

Latest heartbeat timestamp.

localRunIdstring nullable

Desktop-local run id after a queued trigger is claimed.

modelstring nullable

Desktop-facing LLM model id.

previousRunIdstring nullable

Previous run id when this is a retry.

progressMessagestring nullable

Progress message.

progressPercentinteger nullable

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

Remote trigger context.

revisioninteger required

Current run revision.

startedAtstring date-time nullable

Run start timestamp.

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

Lifecycle/status slug. Subscription rows use billing states; background task runs use queued/running/succeeded/failed/stopped.

subUseCasestring nullable

Task-specific usage label.

summarystring nullable

Latest run summary.

temporalClosedAtstring date-time nullable

Temporal close timestamp.

temporalRunIdstring nullable

Temporal run id.

temporalStartedAtstring date-time nullable

Temporal start timestamp.

temporalStatusstring nullable

Last mirrored Temporal status.

temporalWorkflowIdstring nullable

Temporal workflow id for API-worker runs.

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

Trigger source.

useCasestring nullable

High-level usage label.

Example request

{
  "completedAt": "2026-06-04T21:02:00Z",
  "executor": "api",
  "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.",
  "revision": 1,
  "startedAt": "2026-06-04T21:01:00Z",
  "status": "active",
  "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",
  "useCase": "background-task"
}

Response

Updated run mirror.

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