# Manage Watcher Lifecycle
Source: https://docs.chain.link/crec/guides/watchers/manage-lifecycle
Last Updated: 2026-08-31

> For the complete documentation index, see [llms.txt](/llms.txt).

Once a watcher is created (see [Create with Service](/crec/guides/watchers/create-with-service) or [Create with ABI](/crec/guides/watchers/create-with-abi)), you can list, filter, rename, and archive it.

## Status reference

A watcher moves through these states:

(Image: Image)

The entity statuses surfaced by the REST API are `pending`, `active`, `archiving`, `archived`, and `failed` (the API maps internal `archive_failed` to `failed` on the entity response). The richer `archive_failed` state is visible on the `watcher.status` event payload (`apiClient.WatcherEventStatus`).

## List and filter

## Get a single watcher

```go
w, err := client.Watchers.Get(ctx, channelID, watcherID)
if errors.Is(err, watchers.ErrWatcherNotFound) {
    // 404: surface to caller
}
```

The watcher's `Status`, `ChainSelector`, `Address`, and (for service watchers) `Service` are all returned in the response. The `StatusReason` is **not** part of the entity response; subscribe to `watcher.status` events on the channel to receive the human-readable reason whenever the status changes.

## Update metadata (name only)

The SDK only supports updating the watcher **name**. Address, ABI, service, and chain selector are immutable; create a new watcher to change them.

## Archive

Archiving is **asynchronous**. The PATCH returns HTTP **202** with the watcher in `archiving`; you must poll until it reaches `archived` or `archive_failed`.

## Handling failure states

| Sentinel error                        | Returned by       | Recovery                                                                                                        |
| ------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `watchers.ErrWatcherDeploymentFailed` | `WaitForActive`   | Archive, then re-create; check service config and address.                                                      |
| `watchers.ErrWatcherIsArchiving`      | `WaitForActive`   | Someone archived concurrently; wait for `WaitForArchived`.                                                      |
| `watchers.ErrWatcherAlreadyArchived`  | `WaitForActive`   | Archived watchers cannot return to `active`; create a new one.                                                  |
| `watchers.ErrWatcherArchiveFailed`    | `WaitForArchived` | Subscribe to the `watcher.status` event on the channel to read the `StatusReason`, then retry the archive once. |

## Transient vs. permanent errors

`WaitForActive` and `WaitForArchived` both invoke the SDK's `isTransientError` helper. Transient errors (HTTP **429**, **5xx**, network timeouts, broken pipes) are silently retried at the configured poll interval. Permanent errors (validation, `ctx.Done()`, `4xx` other than 429) abort the wait immediately.

For details on tuning the poll interval and consistency window, see [SDK Configuration](/crec/reference/sdk-configuration).

## Next steps

- [Poll and Search Events](/crec/guides/events/poll-and-search): how the active watcher delivers data.
- [Lifecycles](/crec/reference/lifecycles): full state machines for watchers, wallets, and operations.