Sign in
Background Tasks

Create task run mirror

Changed on

Creates a run mirror for a desktop execution. Use this for local scheduler/manual runs; use /trigger when a remote user action should queue a new local execution.

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

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
  • Auth: HTTP bearer

Path parameters

slugstring required

Task slug.

Example:daily-summary

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

Request body

completedAtstring date-time nullable

Run completion timestamp.

errorstring nullable

Initial run error.

executor'desktop' | 'api'

Execution backend. Defaults from task.executionTarget.

lastHeartbeatAtstring date-time nullable

Latest heartbeat timestamp.

localRunIdstring nullable

Desktop-local run id if different from runId.

modelstring nullable

Desktop-facing LLM model id.

previousRunIdstring nullable

Previous run id when this is a retry.

progressMessagestring nullable

Initial progress message.

progressPercentinteger nullable

Initial progress for polling clients.

providerstring nullable

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

requestedContextstring nullable

Remote trigger context if this run was queued by the API.

runIdstring required

Cloud-visible run id from the desktop.

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

Initial run summary.

temporalRunIdstring nullable

Temporal run id.

temporalStatusstring nullable

Last mirrored Temporal status.

temporalWorkflowIdstring nullable

Temporal workflow id for API-worker runs.

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

Trigger source. Defaults to manual.

useCasestring nullable

High-level usage label.

Example request

{
  "completedAt": "2026-06-04T21:02:00Z",
  "executor": "desktop",
  "lastHeartbeatAt": "2026-06-04T21:01:30Z",
  "localRunId": "local-run-42",
  "model": "openai/gpt-4.1-mini",
  "previousRunId": "run-20260604-205000",
  "progressMessage": "Queued for API worker.",
  "provider": "openai",
  "requestedContext": "Run this now.",
  "runId": "run-20260604-210000",
  "startedAt": "2026-06-04T21:01:00Z",
  "status": "active",
  "subUseCase": "daily-summary",
  "summary": "started",
  "temporalRunId": "00000000-0000-0000-0000-000000000001",
  "temporalStatus": "Started",
  "temporalWorkflowId": "background-task/user/daily-summary/api-trigger-123",
  "trigger": "manual",
  "useCase": "background-task"
}

Response

Created 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