---
title: "Lease items from the queue"
method: POST
path: "/v1/queue.lease"
tags: ["Querator V1"]
---

# Lease items from the queue

`POST /v1/queue.lease`

Lease a items from the requested queue.  When a items is lease by a consumer, that consumer gains exclusive rights to the items. No other consumer will be provided the same items unless the `lease_deadline` has expired 
and the consumer with the lease has not marked the items via  `/queue.complete` or `/queue.retry`

If a items is not acknowledge via `/queue.complete` within the `lease_deadline` period it will be offered to another consumer.

### Timeout Semantics
The call will return when a lease is successful or when `request_timeout` has been reached. If the call returns with a 454 `Retry Request` response code, this means there were no items in the queue and the `request_timeout` was reached. In this case the client should retry the lease request.

The client should NOT cancel the request before `request_timeout` has been reached. If the call fails to return after `request_timeout` is reached the client can safely cancel the request.

## Request body

- QueueLeaseRequest
  - `queue_name` string, required — The name of the queue
  - `client_id` string, required — A unique id which identifies this client. Duplicate client id's are not allowed
  - `request_timeout` string, required — The duration this request should block before the client will cancel the request.
  - `batch_size` integer — The maximum number of items to be leased for this request

## Response `200`

- QueueLeaseResponse
  - `items` QueueLeaseItem[], required
    - `id` string, required — A unique id which identifies an item in a queue
    - `encoding` string — A user specified field which indicates the encoding the user used to encode the payload
    - `kind` string — A user specified field that describes the kind or type the payload contains. Consumers can use this field to determine handling of the payload prior to unmarshalling
    - `reference` string — A user specified field that can be used by the consumer to determine handling of the item without needing to unmarshall the body
    - `attempts` integer — The number of times this item has been retried or leased, and timed out during processing by a consumer
    - `lease_deadline` string, date-time, required — The date time that Querator will offer up this item to another consumer if the consumer reserving this item has not marked it complete. The consumer can use this date to decide if it should finalize it's work if the timeout date has expired.
    - `bytes` string, byte — The payload of the item is an array of raw bytes without a predetermined character set. NOTE: When communicating with Querator and using the `Content-Type: application/json` header, the 'bytes' field will be encoded in base64. This is necessary because byte fields, unlike string fields, can contain non-UTF8 binary data. Since raw bytes cannot be directly represented in JSON, Querator base64 encodes this field for consumers who prefer JSON payloads.
  - `queue_name` string, required — The name of the queue the leased items are from
  - `partition` integer, required — Partition the leased items are from

## Changes

- **2026-07-17** `b67c2fa641f7` — 1 breaking
  - request body became required
- **2025-04-21** `3de0078c9268` — 1 info
  - endpoint added
- **2024-09-15** `ba3240950bb2` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/kapetan-io/apis/querator-api/changes/v1/queue.lease/post.md)

---

[API](https://skmtc.dev/kapetan-io/apis/querator-api.md) · [All operations](https://skmtc.dev/kapetan-io/apis/querator-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kapetan-io/querator-api/revisions/b67c2fa641f7/schema)