Why use a Job instead of an Endpoint
An Endpoint is synchronous application ingress. It should validate, perform bounded work, and respond while the caller is still waiting. A Job is asynchronous application work. It can be started by an Endpoint, but the Endpoint should return a durable Job/operation reference rather than pretend a long task is complete.
The limit model
The configured timeout is a hard part of the Job contract. It is checked when the template is created or updated and enforced at execution time. See Limits and quotas for the distinction between platform ceilings, per-instance policy, form validation, and runtime enforcement.
The 59-minute limit is intentionally not a substitute for an unbounded worker. Split a longer workflow into idempotent stages, persist the handoff state, and schedule or trigger the next Job. That produces recoverable boundaries and avoids tying one execution to a long-held resource or credential.
Configure a template
The Jobs workspace shows template identity, Component, metadata, actor timestamps, and version. Select a template to open its Details panel: the panel separates Runtime input, Concurrency, Retry, and metadata, and offers Run for a deliberate operator invocation. This separation is useful: it makes the settings that change capacity and duplicate-side-effect risk visible before a run is created.componentDigest in the template. The digest stays meaningful across instances with different local version numbers. When repairing the Component, preserve the Template’s current binding unless the operator explicitly approves a migration.
Runtime input from Events and Schedules
The template’s Runtime input is stored asoptions.input and exposed to the Component through api.input('templateInputs'). A Job-targeting Event or Schedule can configure its own Runtime input in Options:
- Override (default) shallowly overlays the automation input onto template defaults; Event or Schedule keys win.
- Replace replaces the whole template input for that execution;
{}clears it.
templateInputs.
Existing automation definitions retain their effective input after migration; definitions using the former default keep Job defaults. The resolved input is retained with the Job; later Event or Schedule edits do not change queued or running Jobs, or their retry input.
Choose and retain the executor
executionPolicy selects who executes the Job. A direct Platform API or MCP invocation requires the caller’s automation permissions. Triggering a Job inside an Endpoint checks the Endpoint’s execution account for those permissions.
Use a dedicated Service Account for unattended work. An explicit policy and
triggerUser must agree; clear the legacy alias with null when replacing it. The Endpoint compatibility migration preserves existing instance Job defaults and template bindings.
Jobs capture their executor when the durable record is created. api.currentUser() returns that executor; Jobs do not have the Endpoint’s separate business-identity setting. History distinguishes executionUserId from initiatedByUserId. A retry keeps the original executor and initiator even if a Template or instance default changes, and rechecks the executor’s availability and current permissions before running.
For example, a human user invokes an Endpoint executing as System with Caller business identity. If that Endpoint triggers a CALLER Job, the Job executes as System, api.currentUser() in the Job is System, and initiatedByUserId remains the original human user. A Template selecting a different Service Account uses that account instead.
The Job executor’s roles authorize operation families, while resource ACLs determine access to particular Databases, Storage objects, and other restricted targets. Configured administrator Service Account execution also requires approved Component and library code. An approval failure produces a terminal error rather than repeatedly retrying unapproved code; inspect the failure and approve the intended executable version before starting new work.
The platform rejects retry backoff above 30 days before queueing. If an absolute requested run time becomes due while the request is being processed, the Job is dispatched immediately; the queue is never given a timestamp in the past.
What a Job gives you
- Did the work start, remain pending, get cancelled, expire, finish, or error?
- Which component version and execution principal were selected?
- Which input/result fields were intentionally hidden from history?
- Was this a retry child, and what happened on the preceding attempt?
- Did a downstream artifact exist and finalize successfully?
Design for retries and timeouts
Jobs are at-least-once from the perspective of external systems. A timeout, worker interruption, or delivery retry can leave the platform without proof that a remote side effect did not happen.- Create an idempotency key per business effect before calling the provider.
- Store/check the provider correlation ID before scheduling a retry.
- Make each stage independently safe to run again.
- Keep remote calls, large file work, and database writes bounded.
- Use a concurrency key for a shared account, file, or customer when two writes would conflict.
- Break work approaching the timeout into resumable chunks; write a checkpoint to a Table or Storage before enqueueing the next chunk.
Operate a Job
Use Jobs → Job History to inspect an exact Job ID, its status, current/selected version, logs, timing, and retry root. “Accepted” means the request created or scheduled durable work; it is not a success result. ConfirmFINISHED or a finalized artifact before notifying users or triggering a dependent business process.
The Trigger reference identifies the Event or Schedule definition that started the Job; the history reference identifies its particular occurrence. For Event Jobs, the definition is resolved from the receipt for that exact Job execution, so two Events targeting the same template remain distinguishable. The list exposes this reference as triggerId and its display name as triggerName. A missing retained definition is shown as unavailable rather than inferred from the template.
For a bulk action, review the selected or filtered scope and eligible count before confirmation. After acceptance, View progress opens the background operation. Review processed, skipped and failed counts: a finished operation can include individual failures. Closing its progress view does not cancel accepted work.
Read attempt status and Job result
Job History separates the status of one attempt from the result of its full retry history:
Outcome summaries cover attempts created after the 1.6.6 cutover. Existing Job rows remain available, but the upgrade does not rebuild their history; their aggregate result can be empty. A new retry of an older Job summarizes the new attempts only. Work already running during the upgrade can finish normally.
Filter Job result to distinguish Failed from Succeeded after retry.
Retry pending includes an accepted retry waiting to start; it does not mean the
history has reached a final failure. In progress, Succeeded, Cancelled
and Expired describe the other outcomes. These filters apply to the complete
query before pagination, rather than only the rows already loaded.
For example, an earlier row can show Attempt status: ERROR and Job result:
Succeeded after retry. Manual retry starts a new run at attempt 1 with a fresh
automatic retry budget, while its outcome remains part of the same Job history.
The attempt number displayed on an older row does not become the latest attempt’s
number. Once no attempt is running or scheduled and no automatic retry is pending,
Retry on an earlier failed or cancelled row starts another manual run. Repeated
clicks while its child is still live reuse that child. Bulk-operation replays retain
their original result ID, even when that attempt has already finished.
Related guides
Automation
Configure schedules, events, webhooks, and retry delivery.
Traces and correlation
Investigate execution and handoff failures.
Components
Build the versioned logic a Job executes.
Agent triggers
Use durable Agents when the work requires planning and tool selection, not one fixed Component.
Cancellation and recovery
Cancelling a pending Job prevents execution. Cancelling a running Job records a durable request; its status remainsPROCESSING until the worker acknowledges that request or
recovery confirms that its execution lease expired. The details panel shows cancellation
as pending during that interval. A cancellation request cannot undo an external action
that already completed.
Accepted Jobs retain their payload, delivery intent and retry lineage independently of
transient cache availability. Delivery retries do not create another business attempt.
A lost worker with an unknown effect is reported as requiring recovery; inspect the
original target before explicitly retrying a write. Automatic retry settings remain
separate from infrastructure delivery and do not guarantee exactly-once external effects.
Follow-up execution through Events
Ordinary Component Jobs publish native success, failed-attempt and final-failure signals. UseJOB_EXECUTION_SUCCEEDED to chain a follow-up Job, JOB_ATTEMPT_FAILED to react to each failed attempt, or JOB_EXECUTION_FAILED to act only when no automatic retry remains. Filter by the source Job template and make the follow-up action idempotent. See Job execution Events for the payload, execution-series identity and cycle protection.