> Documentation index: https://beezr.io/developers/api/llms.txt

# Query records

`POST /api/v4/records/query`

Returns a page of records that match your filters, in the order you choose.
Pages hold 1 to 100 records (default 20). There are more pages while `offset + returned < total`.
File fields come back as references; download a file with `/api/v4/records/content`.


## Requirements

| Requirement | Value |
| --- | --- |
| Auth | `X-API-Key` |
| Counts as | 1 request |
| Idempotency | not supported |
| Batch limit | n/a |

## Headers

| Parameter | Type | Presence | Description |
| --- | --- | --- | --- |
| `X-API-Key` | string | required | Read from your server environment. |
| `Content-Type` | string | required | `application/json`. |

## Body parameters

| Parameter | Type | Presence | Description |
| --- | --- | --- | --- |
| `module` | string | required | The module's table name, shown under the module name on its card in Beezr Designer (for example `cm_equipment_requests_base`). |
| `fields` | array of string | optional | Return only these fields (id always comes back) |
| `filters` | object | optional | `and`: every condition must match. `or`: at least one must match (the OR group is ANDed with the rest). `groups`: nested groups, each ANDed with the rest.  |
| `filters.and` | array of object | optional | — |
| `filters.and[].field` | string | required | A field's System name |
| `filters.and[].operator` | string | required | Values: eq, ne, gt, gte, lt, lte, in, not_in, contains, starts_with, ends_with, is_null, is_not_null. |
| `filters.and[].value` | value | optional | Not used by is_null / is_not_null. An array for in / not_in. |
| `filters.or` | array of object | optional | — |
| `filters.or[].field` | string | required | A field's System name |
| `filters.or[].operator` | string | required | Values: eq, ne, gt, gte, lt, lte, in, not_in, contains, starts_with, ends_with, is_null, is_not_null. |
| `filters.or[].value` | value | optional | Not used by is_null / is_not_null. An array for in / not_in. |
| `filters.groups` | array of object | optional | — |
| `sort` | array of object | optional | — |
| `sort[].field` | string | required | — |
| `sort[].direction` | string | optional | Default asc. Values: asc, desc. |
| `limit` | integer | optional | Values outside 1–100 are clamped Minimum 1. Maximum 100. Default 20. |
| `offset` | integer | optional | Minimum 0. Default 0. |

## Returns

HTTP 200. A page of records.

| Parameter | Type | Presence | Description |
| --- | --- | --- | --- |
| `success` | boolean | optional | — |
| `data` | array of object | optional | — |
| `data[].id` | integer | optional | — |
| `meta` | object | optional | — |
| `meta.total` | integer | optional | Records that match |
| `meta.limit` | integer | optional | — |
| `meta.offset` | integer | optional | — |
| `meta.returned` | integer | optional | Records in this page |

Field values come back in the same form the Designer shows them.

File fields contain references in v4. Read `fileExtension` as returned.

## Errors

| HTTP | Code | What to do |
| --- | --- | --- |
| 400 | [`MISSING_REQUIRED_FIELD`](/developers/api/errors/#missing-required-field) | Send the required body fields. |
| 400 | [`INVALID_FILTER`](/developers/api/errors/#invalid-filter) | Check fields and operators. |
| 400 | [`INVALID_SORT`](/developers/api/errors/#invalid-sort) | Use a module field. |
| 400 | [`KEY_FIELD_UNRESOLVED`](/developers/api/errors/#key-field-unresolved) | Check the module key field. |
| 401 | [`AUTHENTICATION_FAILED`](/developers/api/errors/#authentication-failed) | Check the API key. |
| 404 | [`MODULE_NOT_FOUND`](/developers/api/errors/#module-not-found) | Copy the module table name. |
| 429 | [`RATE_LIMIT_EXCEEDED`](/developers/api/errors/#rate-limit-exceeded) | Wait for the rate-limit reset. |
| 429 | [`TOO_MANY_CONCURRENT_REQUESTS`](/developers/api/errors/#too-many-concurrent-requests) | Wait; keep at most 2 in flight. |
| 429 | [`MONTHLY_QUOTA_EXCEEDED`](/developers/api/errors/#monthly-quota-exceeded) | Stop retries until the 1st. |
| 500 | [`QUERY_FAILED`](/developers/api/errors/#query-failed) | Check the data you sent, then retry once. |
| 500 | [`FIELD_LOAD_FAILED`](/developers/api/errors/#field-load-failed) | Retry later. |
| 500 | [`INTERNAL_ERROR`](/developers/api/errors/#internal-error) | Retry later. |

## Request

```curl
curl --fail-with-body --silent --show-error \
  'https://services.beezr.io/generic/api/v4/records/query' \
  -H "X-API-Key: $BEEZR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "module": "cm_equipment_requests_base",
  "fields": ["title","priority","needed_by"],
  "filters": {"and":[{"field":"priority","operator":"lte","value":2},{"field":"title","operator":"contains","value":"laptop"}]},
  "sort": [{"field":"needed_by","direction":"asc"}],
  "limit": 20,
  "offset": 0
}'
```

```javascript
const response = await fetch("https://services.beezr.io/generic/api/v4/records/query", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BEEZR_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "module": "cm_equipment_requests_base",
    "fields": ["title","priority","needed_by"],
    "filters": {"and":[{"field":"priority","operator":"lte","value":2},{"field":"title","operator":"contains","value":"laptop"}]},
    "sort": [{"field":"needed_by","direction":"asc"}],
    "limit": 20,
    "offset": 0
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```python
import os
import requests

response = requests.post(
    "https://services.beezr.io/generic/api/v4/records/query",
    headers={"X-API-Key": os.environ["BEEZR_API_KEY"]},
    json={
      "module": "cm_equipment_requests_base",
      "fields": ["title","priority","needed_by"],
      "filters": {"and":[{"field":"priority","operator":"lte","value":2},{"field":"title","operator":"contains","value":"laptop"}]},
      "sort": [{"field":"needed_by","direction":"asc"}],
      "limit": 20,
      "offset": 0
    }
)
response.raise_for_status()
print(response.json())
```

## Success response

```json
{
  "success": true,
  "data": [{"id":482913,"title":"laptop"}],
  "meta": {"total":1,"limit":20,"offset":0,"returned":1}
}
```

## Common error

```json
{"success":false,"error":{"code":"AUTHENTICATION_FAILED","message":"Invalid or missing API key"}}
```