---
title: "Watch watches for events happening or that have happened. Both input and output are streams; the input stream is for creating and canceling watchers and the output stream sends events. One watch RPC can watch on multiple key ranges, streaming events for several watches at once. The entire event history can be watched starting from the last compaction revision."
method: POST
path: "/v3/watch"
tags: ["Watch"]
---

# Watch watches for events happening or that have happened. Both input and output are streams; the input stream is for creating and canceling watchers and the output stream sends events. One watch RPC can watch on multiple key ranges, streaming events for several watches at once. The entire event history can be watched starting from the last compaction revision.

`POST /v3/watch`

## Request

- Base URL: `https://etcd.io` (the document declares no server; this is the origin it was published from)
- URL: `https://etcd.io/v3/watch`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/docs/v3/watch/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- EtcdserverpbWatchRequest
  - `cancel_request` EtcdserverpbWatchCancelRequest
    - `watch_id` string, int64: watch_id is the watcher id to cancel so that no more events are transmitted.
  - `create_request` EtcdserverpbWatchCreateRequest
    - `filters` WatchCreateRequestFilterType[]: filters filter the events at server side before it sends back to the watcher.
    - `fragment` boolean: fragment enables splitting large revisions into multiple watch responses.
    - `key` string, byte: key is the key to register for watching.
    - `prev_kv` boolean: If prev_kv is set, created watcher gets the previous KV before the event happens. If the previous KV is already compacted, nothing will be returned.
    - `progress_notify` boolean: progress_notify is set so that the etcd server will periodically send a WatchResponse with no events to the new watcher if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server may decide how often it will send notifications based on current load.
    - `range_end` string, byte: range_end is the end of the range [key, range_end) to watch. If range_end is not given, only the key argument is watched. If range_end is equal to '\0', all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) will be watched.
    - `start_revision` string, int64: start_revision is an optional revision to watch from (inclusive). No start_revision is "now".
    - `watch_id` string, int64: If watch_id is provided and non-zero, it will be assigned to this watcher. Since creating a watcher in etcd is not a synchronous operation, this can be used ensure that ordering is correct when creating multiple watchers on the same stream. Creating a watcher with an ID already in use on the stream will cause an error to be returned.
  - `progress_request` EtcdserverpbWatchProgressRequest: Requests the a watch stream progress status be sent in the watch response stream as soon as possible.

## Response `200`

A successful response.(streaming responses)

- object
  - `error` RuntimeStreamError
    - `details` ProtobufAny[]
      - `type_url` string
      - `value` string, byte
    - `grpc_code` integer
    - `http_code` integer
    - `http_status` string
    - `message` string
  - `result` EtcdserverpbWatchResponse
    - `cancel_reason` string: cancel_reason indicates the reason for canceling the watcher.
    - `canceled` boolean: canceled is set to true if the response is for a cancel watch request. No further events will be sent to the canceled watcher.
    - `compact_revision` string, int64: compact_revision is set to the minimum index if a watcher tries to watch at a compacted index. This happens when creating a watcher at a compacted revision or the watcher cannot catch up with the progress of the key-value store. The client should treat the watcher as canceled and should not try to create any watcher with the same start_revision again.
    - `created` boolean: created is set to true if the response is for a create watch request. The client should record the watch_id and expect to receive events for the created watcher from the same stream. All events sent to the created watcher will attach with the same watch_id.
    - `events` MvccpbEvent[]
      - `kv` MvccpbKeyValue
        - `create_revision` string, int64: create_revision is the revision of last creation on this key.
        - `key` string, byte: key is the key in bytes. An empty key is not allowed.
        - `lease` string, int64: lease is the ID of the lease that attached to key. When the attached lease expires, the key will be deleted. If lease is 0, then no lease is attached to the key.
        - `mod_revision` string, int64: mod_revision is the revision of last modification on this key.
        - `value` string, byte: value is the value held by the key, in bytes.
        - `version` string, int64: version is the version of the key. A deletion resets the version to zero and any modification of the key increases its version.
      - `prev_kv` MvccpbKeyValue
        - `create_revision` string, int64: create_revision is the revision of last creation on this key.
        - `key` string, byte: key is the key in bytes. An empty key is not allowed.
        - `lease` string, int64: lease is the ID of the lease that attached to key. When the attached lease expires, the key will be deleted. If lease is 0, then no lease is attached to the key.
        - `mod_revision` string, int64: mod_revision is the revision of last modification on this key.
        - `value` string, byte: value is the value held by the key, in bytes.
        - `version` string, int64: version is the version of the key. A deletion resets the version to zero and any modification of the key increases its version.
      - `type` 'PUT' | 'DELETE'
    - `fragment` boolean: framgment is true if large watch response was split over multiple responses.
    - `header` EtcdserverpbResponseHeader
      - `cluster_id` string, uint64: cluster_id is the ID of the cluster which sent the response.
      - `member_id` string, uint64: member_id is the ID of the member which sent the response.
      - `raft_term` string, uint64: raft_term is the raft term when the request was applied.
      - `revision` string, int64: revision is the key-value store revision when the request was applied. For watch progress responses, the header.revision indicates progress. All future events recieved in this stream are guaranteed to have a higher revision number than the header.revision number.
    - `watch_id` string, int64: watch_id is the ID of the watcher that corresponds to the response.

## Other responses

- `default`: An unexpected error response

---

[API](https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto.md) - [All operations](https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/llms.txt) - [OpenAPI document](https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/revisions/79259377f328?raw)