---
title: "Txn processes multiple requests in a single transaction. A txn request increments the revision of the key-value store and generates events with the same revision for every completed request. It is not allowed to modify the same key several times within one txn."
method: POST
path: "/v3/kv/txn"
tags: ["KV"]
---

# Txn processes multiple requests in a single transaction. A txn request increments the revision of the key-value store and generates events with the same revision for every completed request. It is not allowed to modify the same key several times within one txn.

`POST /v3/kv/txn`

## Request

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

## Request body

- EtcdserverpbTxnRequest: From google paxosdb paper: Our implementation hinges around a powerful primitive which we call MultiOp. All other database operations except for iteration are implemented as a single call to MultiOp. A MultiOp is applied atomically and consists of three components: 1. A list of tests called guard. Each test in guard checks a single entry in the database. It may check for the absence or presence of a value, or compare with a given value. Two different tests in the guard may apply to the same or different entries in the database. All tests in the guard are applied and MultiOp returns the results. If all tests are true, MultiOp executes t op (see item 2 below), otherwise it executes f op (see item 3 below). 2. A list of database operations called t op. Each operation in the list is either an insert, delete, or lookup operation, and applies to a single database entry. Two different operations in the list may apply to the same or different entries in the database. These operations are executed if guard evaluates to true. 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false.
  - `compare` EtcdserverpbCompare[]: compare is a list of predicates representing a conjunction of terms. If the comparisons succeed, then the success requests will be processed in order, and the response will contain their respective responses in order. If the comparisons fail, then the failure requests will be processed in order, and the response will contain their respective responses in order.
    - `create_revision` string, int64
    - `key` string, byte: key is the subject key for the comparison operation.
    - `lease` string, int64: lease is the lease id of the given key.
    - `mod_revision` string, int64: mod_revision is the last modified revision of the given key.
    - `range_end` string, byte: range_end compares the given target to all keys in the range [key, range_end). See RangeRequest for more details on key ranges.
    - `result` 'EQUAL' | 'GREATER' | 'LESS' | 'NOT_EQUAL'
    - `target` 'VERSION' | 'CREATE' | 'MOD' | 'VALUE' | 'LEASE'
    - `value` string, byte: value is the value of the given key, in bytes.
    - `version` string, int64
  - `failure` EtcdserverpbRequestOp[]: failure is a list of requests which will be applied when compare evaluates to false.
    - `request_delete_range` EtcdserverpbDeleteRangeRequest
      - `key` string, byte: key is the first key to delete in the range.
      - `prev_kv` boolean: If prev_kv is set, etcd gets the previous key-value pairs before deleting it. The previous key-value pairs will be returned in the delete response.
      - `range_end` string, byte: range_end is the key following the last key to delete for the range [key, range_end). If range_end is not given, the range is defined to contain only the key argument. If range_end is one bit larger than the given key, then the range is all the keys with the prefix (the given key). If range_end is '\0', the range is all keys greater than or equal to the key argument.
    - `request_put` EtcdserverpbPutRequest
      - `ignore_lease` boolean: If ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist.
      - `ignore_value` boolean: If ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist.
      - `key` string, byte: key is the key, in bytes, to put into the key-value store.
      - `lease` string, int64: lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.
      - `prev_kv` boolean: If prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response.
      - `value` string, byte: value is the value, in bytes, to associate with the key in the key-value store.
    - `request_range` EtcdserverpbRangeRequest
      - `count_only` boolean: count_only when set returns only the count of the keys in the range.
      - `key` string, byte: key is the first key for the range. If range_end is not given, the request only looks up key.
      - `keys_only` boolean: keys_only when set returns only the keys and not the values.
      - `limit` string, int64: limit is a limit on the number of keys returned for the request. When limit is set to 0, it is treated as no limit.
      - `max_create_revision` string, int64: max_create_revision is the upper bound for returned key create revisions; all keys with greater create revisions will be filtered away.
      - `max_mod_revision` string, int64: max_mod_revision is the upper bound for returned key mod revisions; all keys with greater mod revisions will be filtered away.
      - `min_create_revision` string, int64: min_create_revision is the lower bound for returned key create revisions; all keys with lesser create revisions will be filtered away.
      - `min_mod_revision` string, int64: min_mod_revision is the lower bound for returned key mod revisions; all keys with lesser mod revisions will be filtered away.
      - `range_end` string, byte: range_end is the upper bound on the requested range [key, range_end). If range_end is '\0', the range is all keys >= key. If range_end is key plus one (e.g., "aa"+1 == "ab", "a\xff"+1 == "b"), then the range request gets all keys prefixed with key. If both key and range_end are '\0', then the range request returns all keys.
      - `revision` string, int64: revision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response.
      - `serializable` boolean: serializable sets the range request to use serializable member-local reads. Range requests are linearizable by default; linearizable requests have higher latency and lower throughput than serializable requests but reflect the current consensus of the cluster. For better performance, in exchange for possible stale reads, a serializable range request is served locally without needing to reach consensus with other nodes in the cluster.
      - `sort_order` 'NONE' | 'ASCEND' | 'DESCEND'
      - `sort_target` 'KEY' | 'VERSION' | 'CREATE' | 'MOD' | 'VALUE'
    - `request_txn` EtcdserverpbTxnRequest (recursive)
  - `success` EtcdserverpbRequestOp[]: success is a list of requests which will be applied when compare evaluates to true.
    - `request_delete_range` EtcdserverpbDeleteRangeRequest
      - `key` string, byte: key is the first key to delete in the range.
      - `prev_kv` boolean: If prev_kv is set, etcd gets the previous key-value pairs before deleting it. The previous key-value pairs will be returned in the delete response.
      - `range_end` string, byte: range_end is the key following the last key to delete for the range [key, range_end). If range_end is not given, the range is defined to contain only the key argument. If range_end is one bit larger than the given key, then the range is all the keys with the prefix (the given key). If range_end is '\0', the range is all keys greater than or equal to the key argument.
    - `request_put` EtcdserverpbPutRequest
      - `ignore_lease` boolean: If ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist.
      - `ignore_value` boolean: If ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist.
      - `key` string, byte: key is the key, in bytes, to put into the key-value store.
      - `lease` string, int64: lease is the lease ID to associate with the key in the key-value store. A lease value of 0 indicates no lease.
      - `prev_kv` boolean: If prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response.
      - `value` string, byte: value is the value, in bytes, to associate with the key in the key-value store.
    - `request_range` EtcdserverpbRangeRequest
      - `count_only` boolean: count_only when set returns only the count of the keys in the range.
      - `key` string, byte: key is the first key for the range. If range_end is not given, the request only looks up key.
      - `keys_only` boolean: keys_only when set returns only the keys and not the values.
      - `limit` string, int64: limit is a limit on the number of keys returned for the request. When limit is set to 0, it is treated as no limit.
      - `max_create_revision` string, int64: max_create_revision is the upper bound for returned key create revisions; all keys with greater create revisions will be filtered away.
      - `max_mod_revision` string, int64: max_mod_revision is the upper bound for returned key mod revisions; all keys with greater mod revisions will be filtered away.
      - `min_create_revision` string, int64: min_create_revision is the lower bound for returned key create revisions; all keys with lesser create revisions will be filtered away.
      - `min_mod_revision` string, int64: min_mod_revision is the lower bound for returned key mod revisions; all keys with lesser mod revisions will be filtered away.
      - `range_end` string, byte: range_end is the upper bound on the requested range [key, range_end). If range_end is '\0', the range is all keys >= key. If range_end is key plus one (e.g., "aa"+1 == "ab", "a\xff"+1 == "b"), then the range request gets all keys prefixed with key. If both key and range_end are '\0', then the range request returns all keys.
      - `revision` string, int64: revision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response.
      - `serializable` boolean: serializable sets the range request to use serializable member-local reads. Range requests are linearizable by default; linearizable requests have higher latency and lower throughput than serializable requests but reflect the current consensus of the cluster. For better performance, in exchange for possible stale reads, a serializable range request is served locally without needing to reach consensus with other nodes in the cluster.
      - `sort_order` 'NONE' | 'ASCEND' | 'DESCEND'
      - `sort_target` 'KEY' | 'VERSION' | 'CREATE' | 'MOD' | 'VALUE'
    - `request_txn` EtcdserverpbTxnRequest (recursive)

## Response `200`

A successful response.

- EtcdserverpbTxnResponse
  - `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.
  - `responses` EtcdserverpbResponseOp[]: responses is a list of responses corresponding to the results from applying success if succeeded is true or failure if succeeded is false.
    - `response_delete_range` EtcdserverpbDeleteRangeResponse
      - `deleted` string, int64: deleted is the number of keys deleted by the delete range request.
      - `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.
      - `prev_kvs` MvccpbKeyValue[]: if prev_kv is set in the request, the previous key-value pairs will be returned.
        - `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.
    - `response_put` EtcdserverpbPutResponse
      - `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.
      - `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.
    - `response_range` EtcdserverpbRangeResponse
      - `count` string, int64: count is set to the number of keys within the range when requested.
      - `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.
      - `kvs` MvccpbKeyValue[]: kvs is the list of key-value pairs matched by the range request. kvs is empty when count is requested.
        - `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.
      - `more` boolean: more indicates if there are more keys to return in the requested range.
    - `response_txn` EtcdserverpbTxnResponse (recursive)
  - `succeeded` boolean: succeeded is set to true if the compare evaluated to true or false otherwise.

## 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)