---
title: "Range gets the keys in the range from the key-value store."
method: POST
path: "/v3/kv/range"
tags: ["KV"]
---

# Range gets the keys in the range from the key-value store.

`POST /v3/kv/range`

## 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/range`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/etcd/apis/api-etcdserverpb-rpc-proto/docs/v3/kv/range/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- 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'

## Response `200`

A successful response.

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

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