# Search bins

Operation ID: `searchBins`

Group: Inventory › Bins

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchBins)

`POST /inventory/bins/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches bins. The fields are the same as on the collection. The filters include some the collection doesn't have, such as withoutLimits.

Only GET inventory/bins/:id returns capacity.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: searchBinsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A bin must match every filter you send. Send an empty object to return all bins. Example: `{"withoutLimits":true,"isPickingBin":true}`. |
| `filters.binCode` | string | no | Limits results to the bin with this code. The match is exact. Codes are unique, so this matches at most one bin. |
| `filters.barcode` | string | no | Limits results to the bin with this barcode. The match is exact. Barcodes are unique, so this matches at most one bin. |
| `filters.locationId` | string | no | Limits results to bins in the warehouse with this identifier. An identifier that is not a warehouse matches nothing. See id on GET inventory/warehouses/:id. |
| `filters.aisle` | string | no | Limits results to bins in this aisle. The match is exact. |
| `filters.rack` | string | no | Limits results to bins on this rack. The match is exact. |
| `filters.zone` | string | no | Limits results to bins in this zone. The match is exact. |
| `filters.isPickingBin` | boolean | no | Limits results to picking locations when true, or to bins that are not when false. Omit to match both. |
| `filters.isReceivingBin` | boolean | no | Limits results to bins that stage newly received goods when true, or to bins that do not when false. Omit to match both. |
| `filters.isProductionBin` | boolean | no | Limits results to bins that feed or receive production when true, or to bins that do not when false. Omit to match both. |
| `filters.supportsPerishable` | boolean | no | Limits results to bins that may keep perishable stock when true, or to bins that may not when false. Omit to match both. |
| `filters.capacityCheckMode` | string | no | Limits results to bins with this capacity check mode. Accepted values: 'HardBlock', 'SoftWarning'. |
| `filters.tempZone` | string | no | Limits results to bins in this temperature zone. The match is exact. |
| `filters.active` | boolean | no | Limits results to bins that may be chosen for new movements when true, or to retired ones when false. Omit to match both. |
| `filters.withoutLimits` | boolean | no | True to return only bins with no quantity, weight or volume limit above zero, the ones no capacity check can protect. |
| `filters.modifiedSince` | date-time | no | Limits results to bins changed on or after this time. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The pagination controls. Omit for the first page. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit for the first page. |
| `page.size` | number | no | The number of bins per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

```json
{
  "filters": {
    "withoutLimits": true,
    "isPickingBin": true
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}
```

## Response

`200` Success

Under `data` (searchBinsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The bins on this page, oldest first. An empty array when nothing matches. Example: `[{"id":"8e1c40a7-5b93-4d26-a0f8-3c74e19b5d02","binCode":"A-01-1","barcode":"BIN-A011","locationId":"f5272ae0-0f0b-47d2-b78a-2158fec2cc32","locationCode":"WH-02","locationName":"Main warehouse","aisle":"A","rack":"01","shelfLevel":"1","zone":"Picking","isPickingBin":true,"isReceivingBin":false,"maxQuantity":500,"maxWeight":"250","maxWeightUnit":"Kg","capacityCheckMode":"HardBlock","tempZone":"Ambient","supportsPerishable":false,"active":true,"lastModifiedDate":"2026-08-18T09:14:22.517Z"}]`. |
| `items[].id` | string | yes | The unique identifier for the bin. |
| `items[].binCode` | string | no | The short code that identifies the bin, for example 'A-01-1'. It is unique within the tenant, not per warehouse, and cannot be changed after the bin is created. |
| `items[].barcode` | string | no | The barcode printed on the bin label. It is unique within the tenant and cannot be changed after the bin is created. |
| `items[].locationId` | string | no | The unique identifier for the warehouse the bin is in. It cannot be changed after the bin is created. See id on GET inventory/warehouses/:id. |
| `items[].locationCode` | string | no | The code of that warehouse. |
| `items[].locationName` | string | no | The name of that warehouse. |
| `items[].aisle` | string | no | The aisle in the warehouse layout. |
| `items[].rack` | string | no | The rack within the aisle. |
| `items[].shelfLevel` | string | no | The shelf level within the rack. |
| `items[].zone` | string | no | The logical zone of the bin, as your tenant names them. For example 'Picking', 'Storage' or 'Quarantine'. |
| `items[].itemPosition` | string | no | The position within the shelf, where a bin is subdivided further. |
| `items[].isPickingBin` | boolean | no | Whether the bin is a picking location, a fast-access place stock is taken from to fulfill shipments. |
| `items[].isReceivingBin` | boolean | no | Whether the bin stages newly received goods before they are put away. |
| `items[].isProductionBin` | boolean | no | Whether the bin feeds or receives production. |
| `items[].maxQuantity` | number | no | The largest number of units the bin will hold. It is meaningful only when everything in the bin is counted in the same unit. |
| `items[].maxWeight` | decimal | no | The largest weight the bin will hold, in maxWeightUnit. |
| `items[].maxWeightUnit` | string | no | The unit maxWeight is given in. Possible values: 'G', 'Kg', 'Lbs'. |
| `items[].maxVolume` | decimal | no | The largest volume the bin will hold, in maxVolumeUnit. |
| `items[].maxVolumeUnit` | string | no | The unit maxVolume is given in. Possible values: 'L'. |
| `items[].capacityCheckMode` | string | no | What happens when a movement would exceed a limit. Possible values: 'HardBlock', which refuses the movement, and 'SoftWarning', which allows it and flags it. |
| `items[].tempZone` | string | no | The temperature zone the bin belongs to, as your tenant names them. For example 'Ambient', 'Chilled' or 'Frozen'. |
| `items[].tempMin` | decimal | no | The lowest temperature kept in the bin, in degrees Celsius. |
| `items[].tempMax` | decimal | no | The highest temperature kept in the bin, in degrees Celsius. |
| `items[].supportsPerishable` | boolean | no | Whether perishable stock may be kept in the bin. |
| `items[].active` | boolean | no | Whether the bin may be chosen for new movements. When false, the stock already in the bin stays there but no new movement can be assigned to it. |
| `items[].createdDate` | date-time | no | The date and time the bin was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the bin record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `pagination` | object | yes | The pagination cursor for this page. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | no | True when more bins remain beyond this page. |

```json
{
  "data": {
    "items": [
      {
        "id": "8e1c40a7-5b93-4d26-a0f8-3c74e19b5d02",
        "binCode": "A-01-1",
        "barcode": "BIN-A011",
        "locationId": "f5272ae0-0f0b-47d2-b78a-2158fec2cc32",
        "locationCode": "WH-02",
        "locationName": "Main warehouse",
        "aisle": "A",
        "rack": "01",
        "shelfLevel": "1",
        "zone": "Picking",
        "isPickingBin": true,
        "isReceivingBin": false,
        "maxQuantity": 500,
        "maxWeight": "250",
        "maxWeightUnit": "Kg",
        "capacityCheckMode": "HardBlock",
        "tempZone": "Ambient",
        "supportsPerishable": false,
        "active": true,
        "lastModifiedDate": "2026-08-18T09:14:22.517Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error