Sign in
Background Tasks

Get background task mirror

Fetches one task mirror by slug for the authenticated user. Tenant scoping ensures the same slug can exist for different users without leaking data.

get/v1/background-tasks/{slug}

Request

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

Path parameters

slugstring required

Task slug.

Example:daily-summary

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

Response

Task mirror.

activeboolean required

Whether the background task is active for scheduling and remote trigger pickup.

createdAtstring date-time required

Original desktop task creation timestamp when known; otherwise the server row creation time.

executionTarget'desktop' | 'api' required

Where this task executes. desktop preserves the local-first path; api dispatches to the Temporal-backed API worker.

idstring uuid required

Stable UUID primary key.

instructionsstring required

Background task instructions mirrored from task.yaml.

lastAttemptAtstring date-time nullable

Last time the desktop attempted to run this task.

lastRunAtstring date-time nullable

Last time the desktop completed or recorded a run for this task.

lastRunErrorstring nullable

Latest run error, empty when the latest run did not fail.

lastRunIdstring nullable

Last desktop or remote-trigger run id mirrored for this task.

lastRunSummarystring nullable

Short summary from the latest run.

modelstring nullable

Desktop-facing LLM model id.

namestring required

Human-readable background task name.

providerstring nullable

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

revisioninteger required

Optimistic-lock revision used by write endpoints.

scheduleSyncErrorstring nullable

Latest schedule reconciliation error, empty when healthy.

scheduleSyncState'current' | 'syncing' | 'failed' | 'paused' required

Server-owned Temporal schedule reconciliation state.

scheduleSyncedAtstring date-time nullable

Last successful schedule reconciliation timestamp.

slugstring required

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

systemManagedboolean required

Whether Oppulence owns and upgrades this definition. Managed tasks can be paused but not deleted or edited.

templateSlugstring nullable

First-party template that owns this definition. Empty for user-authored tasks.

templateVersioninteger

Installed version of the owning first-party template. Zero for user-authored tasks.

triggersunknown
updatedAtstring date-time required

Server timestamp for the last mirrored task update.

Example response

{
  "active": true,
  "createdAt": "2026-06-04T20:38:00Z",
  "executionTarget": "desktop",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "instructions": "Summarize important account changes.",
  "lastAttemptAt": "2026-06-04T21:00:00Z",
  "lastRunAt": "2026-06-04T21:02:00Z",
  "lastRunId": "run-20260604-210000",
  "lastRunSummary": "No high-priority account changes.",
  "model": "openai/gpt-4.1-mini",
  "name": "Daily Account Summary",
  "provider": "openai",
  "revision": 2,
  "scheduleSyncState": "current",
  "scheduleSyncedAt": "2026-06-04T20:39:00Z",
  "slug": "daily-summary",
  "templateSlug": "relationship-refresh",
  "templateVersion": 1,
  "triggers": {
    "cronExpr": "0 9 * * *",
    "timezone": "America/New_York"
  },
  "updatedAt": "2026-06-04T20:39:00Z"
}

Changes

No operation changes recorded.