Activity Operations

View Markdown

This page discusses the following:

• Pause
• Unpause
• Reset
• Update Options
• Standalone Activity operator commands
• Observability

Activity Operations are deliberate actions you perform on a specific Activity Execution, as opposed to lifecycle behaviors like retries and timeouts which happen automatically.

You can perform Activity Operations through the CLI, the UI, or directly through the gRPC API. Interface support differs between Workflow Activities and Standalone Activities. Activity Operations don't apply to Local Activities. For Standalone Activities, see Standalone Activity operator commands.

Public Preview

Activity Operations are in Public Preview. Pause, Unpause, and Reset are available in Server v1.28.0+. Self-hosted UI requires v2.47.0+.

Activity Operations aren't available as SDK client methods. They're operational controls designed for the CLI, UI, and gRPC API - not for programmatic use in Workflow or Activity code.

Operations summary

Operation	What it does	CLI
Pause	Stops retries. In-flight execution continues unless the Activity uses Heartbeat.	temporal activity pause
Unpause	Resumes a Paused Activity. The next execution starts after any remaining retry backoff or start delay.	temporal activity unpause
Reset	Clears retry state (attempts, backoff) and schedules the Activity for execution again.	temporal activity reset
Update Options	Changes Activity options (for example, timeouts, Retry Policy, or Task Queue) without restarting it.	temporal activity update-options

Pause

Pause stops the Temporal Service from scheduling new retries of an Activity Execution.

When to Pause

• An Activity is calling an external service that's experiencing issues, and you want to stop retries until the service recovers.
• You need to inspect or change configuration before the Activity retries.
• You're rolling out a new Worker version and want to hold specific Activities until the deploy is complete.

What happens when you Pause an Activity

• No further retries are scheduled. The Temporal Service stops scheduling retries.
• Heartbeating determines whether an interruption is sent to the in-flight Activity Task Execution:
  • For Activities with Heartbeat, the interruption is sent with the next Heartbeat response. The SDK raises a Pause-specific error; the Activity can catch this error to clean up resources before exiting.
  • Activities without Heartbeat continue running. If the Activity Task Execution succeeds, its result is delivered to the Workflow. If it fails, no retry is scheduled. Pause takes effect after the in-flight execution ends.
• Pause is idempotent. Pausing an already-Paused Activity has no effect. Pausing a completed Activity returns an error.
• Pausing an Activity doesn't affect the parent Workflow. The Workflow continues Running, and Signals, Queries, and Updates on the parent Workflow are unaffected.
• Workflow code has no visibility into Activity Operations. Pause doesn't produce an Event History event, so the Workflow can't detect or react to it. See Observability.

CLI usage

temporal activity pause \
  --workflow-id my-workflow \
  --activity-id my-activity \
  --reason "Downstream API is down, pausing until recovery"

See the CLI reference for temporal activity pause for all options.

Detect Pause in Activity code

Activities with a Heartbeat can detect that an interruption was caused by Pause rather than by a timeout or Workflow Cancellation. A Paused Activity resumes later. A Cancelled Activity doesn't. Your Activity code may need to handle these cases differently, for example releasing held resources on Pause while preserving them on Cancellation, or vice versa.

SDK	Version	How to detect Pause
Go	v1.34.0+	Catch activity.ErrActivityPaused
Java	v1.29.0+	Catch ActivityPausedException
TypeScript	v1.12.3+	Check cancellationDetails.paused === true
Python	v1.12.0+	Check cancellation_details().paused on asyncio.CancelledError
.NET	v1.7.0+	Check CancellationDetails.IsPaused on OperationCanceledException

Interaction with Workflow Pause

Workflow Pause and Activity Pause are independent. Both stop Activity retries, but they must be Unpaused separately.

• Workflow Pause blocks retries but doesn't interrupt in-flight Activity Task Executions via Heartbeat. Activity Pause does.
• If both are active, both must be Unpaused before the Activity resumes.

Important considerations

• A Paused Activity can still time out. Pause doesn't stop or extend the Schedule-To-Close Timeout. Use update-options to adjust the timeout if needed.
• Pause won't interrupt an Activity that doesn't Heartbeat. The current execution runs to completion, which could take up to the full Start-To-Close Timeout.

Limitations

• Pause operates on individual Activities by ID within a single Workflow. Unlike Unpause, Reset, and Update Options, there's no --query flag. To pause multiple Activities, issue separate commands for each Activity ID.
• No Namespace-wide query for Paused Activities. You must know the Workflow ID. See Observability.

Unpause

Unpause resumes a Paused Activity Execution.

When to Unpause

• The downstream service or dependency that caused you to Pause has recovered.
• A code deploy or configuration change is complete and the Activity is safe to retry.
• You Paused an Activity for investigation and are ready to let it proceed.

What happens when you Unpause an Activity

• The Activity is rescheduled for its next attempt. The next attempt starts after any remaining retry backoff or Start Delay.
• Attempt and Heartbeat state are preserved by default. Use --reset-attempts to restart from attempt 1 and clear the current retry interval when Unpausing.

Unpause is idempotent. Unpausing an Activity that isn't Paused has no effect. Unpausing an Activity that has already completed returns an error.

CLI usage

temporal activity unpause \
  --workflow-id my-workflow \
  --activity-id my-activity

See the CLI reference for temporal activity unpause for all options.

Important considerations

• Unpausing many Activities at once can overwhelm downstream services. If you Paused multiple Activities because a service was down, Unpausing them all at the same time sends all retries simultaneously. Consider Unpausing in batches to avoid overwhelming a recovering service.
• Unpausing doesn't override Workflow Pause. If the parent Workflow is also Paused, Unpausing the Activity alone isn't enough. Both must be Unpaused before the Activity resumes. See Interaction with Workflow Pause.
• Unpausing doesn't reset the attempt count by default. The Activity retries from its current attempt number. Use --reset-attempts when Unpausing, or use Reset, to restart from attempt 1.
• A Paused Activity can time out before you Unpause it. The Schedule-To-Close Timeout isn't stopped or extended while Paused. Use update-options to extend the timeout before Unpausing if needed.
• Unpause doesn't interrupt or duplicate an in-flight execution. If an Activity without Heartbeat is still running when you Unpause, it continues to completion. The Temporal Service doesn't schedule a concurrent execution. If the in-flight execution fails, the next retry proceeds normally.

Reset

Reset clears an Activity's retry state and schedules it to start again from attempt 1.

When to Reset

• An Activity has exhausted most of its retries, and you want to give it its full retries after fixing the underlying issue.
• A Paused Activity needs to start clean after a configuration change or code deploy.
• You want to retry immediately instead of waiting for the next backoff interval.
• A batch of Activities failed due to a transient issue and you want to restart them all with staggered jitter.

What happens when you Reset an Activity

• The attempt count resets to 1. The Activity gets a full set of retry attempts regardless of how many it had used.
• Retry backoff is discarded. If the Activity was in a backoff wait, it's rescheduled to run immediately.
• If the Activity is Paused, Reset also Unpauses it. Use --keep-paused to Reset without Unpausing. With --keep-paused, the attempt count and Heartbeat data are reset, but the Activity stays Paused. No attempt is scheduled until you Unpause separately.
• Resetting an Activity doesn't affect the parent Workflow. The Workflow continues Running, and Signals, Queries, and Updates on the parent Workflow are unaffected.
• Workflow code has no visibility into Activity Operations. Reset doesn't produce an Event History event, so the Workflow can't detect or react to it. See Observability.
• Heartbeating determines whether an interruption will be sent to an in-flight execution:
  • For Activities with Heartbeat, an interruption is sent with the next Heartbeat response. The SDK raises a Reset-specific error so the Activity can clean up before exiting. The next execution starts at attempt 1.
  • Activities without Heartbeat continue running to completion. Reset doesn't cancel, interrupt, or schedule a concurrent execution. If the Activity was running on the Worker, attempt 1 is scheduled to start after the attempt finishes. If the attempt succeeds, the Reset request is ignored and the Activity completes successfully.

CLI usage

temporal activity reset \
  --workflow-id my-workflow \
  --activity-id my-activity

# Reset retry state but don't resume yet
temporal activity reset \
  --workflow-id my-workflow \
  --activity-id my-activity \
  --keep-paused

See the CLI reference for temporal activity reset for all options, including bulk mode via --query.

Detect Reset in Activity code

Activities with a Heartbeat can detect that an interruption was caused by Reset rather than by a timeout or Workflow Cancellation. A Reset Activity will be retried from attempt 1. A Cancelled Activity won't be retried. Your Activity code may need to handle these cases differently, for example saving partial progress on Reset while discarding it on Cancellation.

SDK	How to detect Reset
Go	activity.GetCancellationDetails(ctx).Cause() returns activity.ErrActivityReset
Java	Catch ActivityResetException
TypeScript	Catch ApplicationFailure with error.type === "ActivityReset"
Python	Check cancellation_details().reset on asyncio.CancelledError
.NET	Check CancellationDetails.IsReset on OperationCanceledException

Important considerations

• A Reset Activity can still time out. Reset doesn't restart the Schedule-To-Close Timeout. The deadline is calculated from when the Activity was originally scheduled. Use update-options to extend the timeout before or after Reset.
• Heartbeat details are cleared. If your Activity uses Heartbeat details for progress tracking, the next attempt starts without those details after Reset.
• Reset won't interrupt an Activity that doesn't Heartbeat. The current execution runs to completion, which could take up to the full Start-To-Close Timeout. If the current attempt succeeds, the Activity completes successfully and the Reset request is ignored.
• --restore-original-options restores the Activity's original configuration. It reverts any changes to timeouts, Retry Policy, and Task Queue back to the values they had when the Activity was first scheduled.
• Bulk Reset can overwhelm downstream services. When using --query to Reset Activities across many Workflows, use --jitter to stagger the restart times.

Update Options

An Activity's runtime configuration can be changed without restarting it.

When to Update Options

• The Schedule-To-Close Timeout is about to expire on a Paused Activity, and you need to extend it before Unpausing.
• An Activity's Retry Policy needs tuning based on observed failure patterns (for example, increasing the backoff interval or maximum attempts).
• You want to move an Activity to a different Task Queue to route it to a specific set of Workers.
• You need to restore an Activity's original configuration after a temporary override.

What happens when you Update an Activity's Options

You can change timeouts (Schedule-To-Close, Start-To-Close, Schedule-To-Start, Heartbeat), Retry Policy (initial interval, maximum interval, backoff coefficient, maximum attempts), and Task Queue. Only the fields you specify are changed. All other options remain unchanged.

• If the Activity is waiting for its Start Delay or retry backoff, the new options take effect immediately. Any pending timer is regenerated with the updated configuration.
• If the Activity is currently running, the new options take effect on the next attempt. The in-flight execution isn't interrupted or affected.
• If the Activity is Paused, the new options are stored immediately and will affect the next attempt on Unpause.
• Workflow code has no visibility into Activity Operations. No Event History event is produced for Update Options, so the Workflow can't detect or react to it. See Observability.

The operation is idempotent. Updating an Activity with the same values it already has produces no change. Updating options on an Activity that has already completed returns an error.

CLI usage

temporal activity update-options \
  --workflow-id my-workflow \
  --activity-id my-activity \
  --schedule-to-close-timeout 24h

See the CLI reference for temporal activity update-options for all options, including Retry Policy, Task Queue, and bulk mode via --query.

Important considerations

• --restore-original-options can't be combined with other option changes. It replaces the current options with the values captured when the Activity was first scheduled.

UI support

Update Options is available in the UI. The UI shows Activity operator controls when connected to Temporal Server v1.32.0 or later.

Standalone Activity operator commands

Standalone Activity operator commands target a top-level Standalone Activity instead of an Activity scheduled by a Workflow.

To target a Standalone Activity, provide --activity-id and omit --workflow-id. If the Activity ID has multiple runs, use --run-id to select a specific Activity Run. Without --run-id, the command targets the latest run.

temporal activity pause \
  --activity-id my-standalone-activity \
  --run-id 42016101-b6f7-4812-991b-d58b70c74a54

These commands have the following common behavior:

• They operate on one Standalone Activity Execution at a time. The --query batch mode applies to Workflow Activities, not Standalone Activities.
• A missing Activity Execution returns a NotFound error. A terminal Activity Execution can't be Paused, Unpaused, Reset, or updated.
• Cancellation takes precedence after it has been requested. Pause and Reset are rejected while cancellation is pending, but an Activity can still be cancelled while Pause or Reset is pending.
• Workflow timeouts don't apply. Schedule-To-Close, Schedule-To-Start, Start-To-Close, and Heartbeat timeouts still apply to the Standalone Activity.
• Pause and Reset don't restart the Schedule-To-Close period. Its deadline is the Activity's Schedule Time plus any Start Delay and the Schedule-To-Close Timeout.
• Schedule-To-Start begins when an attempt becomes eligible for dispatch. Start-To-Close and Heartbeat timeouts apply while a Worker is running an attempt.
• Before the first Worker pickup, an operation can't dispatch the Activity before its remaining Start Delay. After the first pickup, Start Delay no longer affects later attempts.

Pause a Standalone Activity

Pause prevents the Temporal Service from dispatching another attempt.

temporal activity pause \
  --activity-id my-standalone-activity \
  --reason "Waiting for the downstream service to recover"

If the Activity is waiting for dispatch, Pause invalidates its pending dispatch and moves it to the Paused state. No Worker receives the Activity until you Unpause it or Reset it without --keep-paused.

If a Worker is already running an attempt, the pause remains pending:

• The Worker keeps its task token, and the current Start-To-Close and Heartbeat timeouts remain in effect.
• The next Heartbeat response tells the Worker that the Activity was Paused.
• If the attempt succeeds, the Activity completes and the pending Pause has no effect.
• If the attempt fails or times out and another retry is permitted, the Activity becomes Paused instead of dispatching the retry. The failed attempt still counts toward the Retry Policy.
• If the failure is non-retryable, no attempts remain, or Schedule-To-Close expires, the Activity closes instead of becoming Paused.

Pause doesn't clear the attempt count, retry state, or Heartbeat details. A fully Paused Activity can still reach its Schedule-To-Close deadline.

Pausing an already-Paused Activity returns a FailedPrecondition error. At the gRPC API level, retrying a Pause request with the same request ID is an idempotent no-op, including after a later Unpause. Pause is also rejected while Reset or Cancellation is pending.

Unpause a Standalone Activity

Unpause resumes a Paused Standalone Activity.

temporal activity unpause \
  --activity-id my-standalone-activity

For a fully Paused Activity, Unpause creates a new dispatch and Schedule-To-Start timer. By default, the Activity keeps its current attempt count, Heartbeat details, and any remaining Retry Policy backoff or Worker-provided Next Retry Delay. The dispatch occurs after the latest of the Unpause time, the preserved retry time, and any remaining Start Delay.

You can change that behavior when Unpausing:

• --reset-attempts resets the attempt count to 1 and discards the current retry interval.
• --jitter adds a random delay within the specified duration.

If Pause is still pending on a running attempt, Unpause cancels the pending Pause. The Worker continues with the same task token and timers, and no new attempt is dispatched. Reset and jitter options don't alter that in-flight attempt.

If a Reset with --keep-paused is pending on a running attempt, Unpause removes only the keep-paused intent. Reset remains pending, and attempt 1 is dispatched when the running attempt yields.

Unpausing an Activity that isn't Paused is an idempotent no-op. Unpausing a terminal Activity returns an error.

Reset a Standalone Activity

Reset clears retry and Heartbeat state and schedules, or requests, attempt 1.

temporal activity reset \
  --activity-id my-standalone-activity

Reset applies immediately when no Activity Task Execution is in flight. This includes an Activity that is waiting for its initial Start Delay, scheduled or dispatched but not yet picked up by a Worker, waiting for retry backoff, or fully Paused. Applying Reset immediately:

• Sets the attempt count to 1.
• Clears retry backoff, the last Heartbeat time, and Heartbeat details.
• Creates a new dispatch and Schedule-To-Start timer unless the Activity remains Paused.
• Unpauses a Paused Activity unless you set --keep-paused. With --keep-paused, the state is reset but no dispatch is created until a later Unpause.
• Applies --jitter to the new dispatch. Before the first Worker pickup, any remaining Start Delay still applies. Reset can therefore apply immediately even though the next attempt isn't dispatched immediately.

Reset remains pending when a Worker has picked up an Activity Task and that attempt is still in flight. It doesn't invalidate the Worker task token or current attempt timers. This remains true if the Worker stops responding: Reset is pending until the attempt reports an outcome or reaches Start-To-Close or Heartbeat Timeout. The next Heartbeat response tells the Worker that the Activity was Reset. If the attempt succeeds, the Activity completes and Reset has no effect. If it fails or times out, Reset applies and schedules attempt 1—even if the failure is non-retryable or the previous Retry Policy had no attempts remaining—provided another attempt fits within the unchanged Schedule-To-Close deadline.

Reset while Pause is pending clears the Pause by default. Set --keep-paused to have the Activity become fully Paused at attempt 1 when the running attempt yields.

Reset always clears Heartbeat details. For a running attempt, the details are cleared when Reset is applied. Reset doesn't create a new Schedule-To-Close period, so attempt 1 must still fit within the original Activity Execution deadline.

Use --restore-original-options to restore the Task Queue, timeouts, Retry Policy, Priority, and Start Delay captured when the Standalone Activity was created. Start Delay is restored only before the first attempt starts. A restore is immediate for an Activity without a running attempt and deferred for a running Activity, so it doesn't change the in-flight attempt. If that attempt succeeds, neither Reset nor the deferred restore is applied.

Reset is rejected if Cancellation or another Reset is already pending, or if the Activity is terminal.

Update Standalone Activity options

A Standalone Activity's stored options can be changed without Resetting it.

temporal activity update-options \
  --activity-id my-standalone-activity \
  --schedule-to-close-timeout 24h \
  --retry-maximum-attempts 20

The server supports the following updates. CLI flags are shown where available; the other fields can be updated directly through the gRPC API.

Option	CLI flag	gRPC update_mask path
Task Queue	--task-queue	task_queue.name
Schedule-To-Close Timeout	--schedule-to-close-timeout	schedule_to_close_timeout
Schedule-To-Start Timeout	--schedule-to-start-timeout	schedule_to_start_timeout
Start-To-Close Timeout	--start-to-close-timeout	start_to_close_timeout
Heartbeat Timeout	--heartbeat-timeout	heartbeat_timeout
Retry Policy or a supported subfield	--retry-* flags	retry_policy or a supported subfield
Priority or a supported subfield	gRPC only	priority or a supported subfield
Start Delay	gRPC only	start_delay

Only fields selected by the update mask change. Through gRPC, you can instead set restore_original to restore the options captured when the Activity was created. restore_original can't be combined with an update mask, and it restores Start Delay only before the first attempt starts.

Updates have the following effects:

• Schedule-To-Close is recalculated and its timer is reissued. Extending it can allow retries that previously wouldn't fit; setting it to zero disables that timeout when Start-To-Close remains set.
• Updating Start-To-Close or Heartbeat Timeout can affect an attempt that is already running. The new deadlines are calculated from that attempt's start time or its last Heartbeat time.
• A Task Queue change affects future dispatches, not an Activity Task that a Worker has already accepted.
• Retry Policy subfield updates are merged with the current policy and validated. A pending policy-derived retry interval is recalculated, but a Worker-provided Next Retry Delay is preserved.
• A waiting Activity is redispatched using the updated options. A fully Paused Activity stores the options without dispatching and uses them after Unpause.
• Options can be updated while Pause, Reset, or Cancellation is pending. Changes to running-attempt timeouts can still affect that attempt.

Start Delay can be updated while the first dispatch is still in its delay window. It can also be updated while the Activity is fully Paused before its first attempt, even if the previous delay has elapsed. After the first attempt has been dispatched, Start Delay can't be changed.

Updating a terminal Activity returns an error.

Timeout validation requirements

Updated timeout values are validated and normalized after the update:

• Each updated timeout must be a valid, non-negative duration.
• An Activity must have either Schedule-To-Close or Start-To-Close Timeout set.
• If Schedule-To-Close Timeout is set, missing Schedule-To-Start and Start-To-Close values are set from it, and longer values are capped to it.
• If only Start-To-Close Timeout is set, Schedule-To-Close and Schedule-To-Start can remain unset for a Standalone Activity.
• Heartbeat Timeout can't exceed Start-To-Close Timeout.

Standalone Activity operation limitations

Pause, Unpause, Reset, and Update Options are available for Standalone Activities through the CLI, gRPC API, and the UI. The UI shows these controls when connected to Temporal Server v1.32.0 or later.

• Standalone Activities don't support batch Pause, Unpause, Reset, or Update Options by Visibility Query.
• The current state is available from temporal activity describe, but Standalone Activities don't have an Event History containing an audit trail of operator commands.

Observability

Activity Operations have a limited audit trail because they are not recorded in a Workflow's Event History. You can use the CLI or the UI to inspect the current state of Workflow Activities and Standalone Activities.

Check Activity state

For a Workflow Activity, temporal workflow describe shows each pending Activity's state, current attempt count, and last failure. The UI also shows who performed an operation, when, and why if a --reason was provided.

For a Standalone Activity, use the UI or temporal activity describe --activity-id <id>. In the CLI output, the RunState field distinguishes Paused from PauseRequested, where a Worker is still running the current attempt.

Find Paused Activities

The TemporalPauseInfo Search Attribute is filterable within a Workflow. TemporalPauseInfo is only added to Workflows; it doesn't exist for Standalone Activities.

There's no Namespace-wide query to find all Paused Activities across Workflows. You must know the Workflow ID.

Standalone Activities have their own Visibility records. To find fully Paused Standalone Activities, use:

temporal activity list --query "ExecutionStatus = 'Paused'"

Audit trail

Activity Operations don't produce Event History events. There is no record of a Pause, Reset, or option change in a Workflow's Event History. Nothing that reads the Event History - Workflow code, Replays, or external tooling - will see that an Operation occurred. Standalone Activities don't have a Workflow Event History.

Evidence of an Operation is gone when the Activity completes or the Workflow closes. There's no persistent record that an Activity was Paused, Reset, or had its options changed.

Use temporal workflow describe, temporal activity describe, or the UI for Workflow Activities to confirm current state.