# Update Activity Options

> For the complete documentation index, see [llms.txt](https://docs.temporal.io/llms.txt).
> Any documentation page is available as raw Markdown by appending `.md` to its URL.
> For related questions, query https://docs.temporal.io/api/retrieve?q=<question>&jtb=<job-to-be-done>&src=md-page&agent=<your-name> (no auth; returns JSON `{content, source_url, page_url}`, with `source_url` pointing to Markdown for docs pages). Don't include personal data or credentials.
> If this page is wrong or missing something you needed, or Temporal behaves differently from what it says, report it with https://docs.temporal.io/api/feedback?title=<summary>&message=<what-happened>&category=documentation&page_url=/activity-operations/update-options&src=md-page&agent=<your-name> (use `category=product` when the product, not the page, is wrong). Report only a specific problem you hit, send it once, and don't include personal data or credentials.

> Change an Activity's timeouts, Retry Policy, or Task Queue while it runs, without restarting the Execution or losing retry state.

Update Options changes an Activity's runtime configuration without restarting it.

## When to Update Options

- The [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout) is about to
  expire on a Paused Activity, and you need to extend it before Unpausing. Extend the
  [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) in the same command if the
  next attempt also needs more time.
- An Activity's [Retry Policy](/encyclopedia/retry-policies) 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](/task-queue) to route it to a specific set of
  [Workers](/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](/encyclopedia/detecting-activity-failures) (Schedule-To-Close, Start-To-Close,
Schedule-To-Start, Heartbeat), Retry Policy (initial interval, maximum interval, backoff coefficient, maximum attempts),
Task Queue, and [Priority](/develop/task-queue-priority-fairness) (priority key, fairness key, fairness weight). For a
Standalone Activity that hasn't dispatched its first Activity Task yet, you can also change the
[Start Delay](/standalone-activity#start-delay). The CLI doesn't have flags for Priority, so change it through the API.

The request carries a field mask naming the fields to change. Fields the mask names are assigned the value in the
request, and fields it doesn't name are left alone. A field the mask names but leaves empty is cleared, not skipped.
`temporal activity update-options` adds a field to the mask only for the flags you pass, so omitting a flag never changes
that option. To clear a timeout from the CLI, pass `0s`. A cleared timeout doesn't stay empty: the Service derives it
again from the other timeouts. See
[Timeouts are resolved again after every update](#timeouts-are-resolved-again-after-every-update).

- **If the Activity is waiting for retry (scheduled),** the new options take effect immediately. Any pending retry timer
  is regenerated with the updated configuration.
- **If the Activity is currently running,** the new options are stored but take effect on the next execution. The
  in-flight execution isn't interrupted.
- **If the Activity is Paused,** the new options are stored immediately. They take effect when the Activity is Unpaused
  and the next execution starts.
- **Workflow code has no visibility into Activity Operations.** Update Options doesn't produce an Event History event,
  so the Workflow can't detect or react to it. See [Observability](/activity-operations#observability).

Update Options 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.

### Timeouts are resolved again after every update

Once the new values are merged in, the Service re-runs the
[Activity timeout rules](/encyclopedia/detecting-activity-failures#timeout-resolution) over the whole set. Changing one
timeout can therefore change another.

The Activity's timeouts were already resolved when it was first scheduled, so none of them is unset by the time you
update. Changing the Schedule-To-Close Timeout works in one direction only:

- **Lowering it pulls the others down with it.** Reduce the Schedule-To-Close Timeout to one hour and a two-hour
  Start-To-Close Timeout is reduced to one hour as well.
- **Raising it leaves the others where they are.** An Activity scheduled with a 24-hour Schedule-To-Close Timeout and no
  Start-To-Close Timeout stores 24 hours for both. Raise the Schedule-To-Close Timeout to 48 hours and the
  Start-To-Close Timeout stays at 24 hours, because it's no longer unset.

To give a Paused Activity both more total time and more time per attempt, change the Schedule-To-Close and
Start-To-Close Timeouts in the same command.

Updates don't apply the Workflow Run Timeout cap that applies at schedule time. Clearing the Schedule-To-Close Timeout
on a Workflow Activity leaves it unbounded rather than falling back to the Workflow Run Timeout.

## CLI usage

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

To target a Standalone Activity, omit `--workflow-id`:

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

See the [CLI reference for `temporal activity update-options`](/cli/command-reference/activity#update-options) for all
options, including Retry Policy and Task Queue.

## Important considerations

- **Changes to a running Activity take effect on the next execution, not the current one.** If you need the change to
  apply immediately, the Activity must finish or fail its current execution first.
- **`--restore-original-options` is batch-only.** This flag only works with `--query`. It's silently ignored in
  single-workflow mode. It can't be combined with other option changes in the same command.
- **Restoring original options requires a stored snapshot.** For Activities that started before your Temporal Service
  supported Activity Operations, no snapshot exists and the request is rejected.
