## List elements

`GET /v1/lists/:iblockId/elements`

Returns list elements with filtering and pagination.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|:---------:|---------|
| `iblockId` (path) | string | yes | — | Numeric list identifier `IBLOCK_ID` or symbolic code `IBLOCK_CODE` |
| `iblockTypeId` (query) | string | no | `lists` | Infoblock type. Values:<br>`lists` — regular lists, default<br>`lists_socnet` — workgroup lists<br>`bitrix_processes` — service workflows<br>`structure` — company-structure type (holds the built-in absence-calendar iblock `absence`) |
| `filter` (query) | string | no | — | JSON filter object over element fields. Key is the field name, value is the condition. Example: `?filter={"NAME":"%report%"}`. Important: pass the WHOLE filter in a single form — either bracket notation or one JSON object. A mixed envelope (`?filter[NAME]=x&filter=`) and a bracket condition deeper than two levels are rejected with `400 INVALID_FILTER`: parsing such a query string would irrecoverably drop half of the conditions. An empty `?filter=` means "no filter". A field that cannot be filtered on is rejected with `422 BITRIX_ERROR`. A filter on `ACTIVE` is accepted and applied: a value other than `Y` or `N` returns an empty array. |
| `select` (query) | string | no | — | Comma-separated list of returned fields. A custom property is requested as `PROPERTY_<id>`. Example: `?select=ID,NAME,PROPERTY_1149`. A name the list does not return causes no error: that field is simply absent from the response. `ID` is always returned, even when it is not in `select` |
| `start` (query) | number | no | 0 | Page offset in steps of 50. Bitrix24 rounds `start` down to a multiple of 50 |
| `offset` (query) | number | no | 0 | Alias of `start`. Applied when `start` is not passed AND the value is greater than zero — zero addresses the same first page as no offset at all. Uses the same 50-record page step |

Place the operator before the field name: no prefix — ordinary comparison, `=` — exact equality, `!` — inequality, `%` — contains a substring, `!%` — does not contain a substring, `>`, `>=`, `<`, `<=` — comparison, `><` — within a range, `!><` — outside a range, `*` — partial full-text search. Supply a two-value array for a range. Examples: `filter={"=NAME":"Report"}`, `filter={"%NAME":"report"}`, `filter={">=ID":500}`, `filter={"><ID":[500,1000]}`. Encode JSON and special characters in the URL with `URLSearchParams` or `curl --get --data-urlencode`.

Bitrix24 returns up to 50 elements per request. Both `start` and its alias `offset` address pages: values 0, 20 and 49 select the first page, while 50 and 70 select the second. A `start` beyond the last page returns the FIRST page again, rather than an empty array. Start at 0, then pass `meta.next` as the next `start`. Stop when `meta.next` is absent or the number of collected elements reaches `meta.total`. Do not wait for an empty page. The `limit` parameter is ignored and does not change the page size.

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/lists/121/elements \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/lists/121/elements \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/121/elements', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
console.log(`Elements: ${meta.total}`, data)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/121/elements', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, meta } = await res.json()
```

## Response fields

The set of fields in the response is not fixed: some fields named in `select` may not come back, and elements of the same list carry different sets of keys. A missing field means neither an empty value nor `N`. The activity flag `ACTIVE` is not returned, with or without `select`. To get only active elements, filter with `?filter={"ACTIVE":"Y"}`.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of list elements |
| `data[].ID` | string | Element identifier |
| `data[].NAME` | string | Element name |
| `data[].IBLOCK_SECTION_ID` | string or null | Section identifier, `null` for an element outside sections |
| `data[].PROPERTY_<id>` | object | Custom property values. Key is the property identifier from [List fields](/docs/lists/fields). The value shape is described in the "Known specifics" section |
| `meta.total` | number | Total number of elements matching the filter |
| `meta.next` | number | Offset for the next page, as reported by Bitrix24. Pass it as `start`. Absent on the last page |

## Response example

System fields are shown. Custom properties are returned under `PROPERTY_<id>` keys — their shape is shown in [Get element](./get.md).

```json
{
  "success": true,
  "data": [
    { "ID": "501", "NAME": "Sample element", "IBLOCK_SECTION_ID": null },
    { "ID": "502", "NAME": "Draft", "IBLOCK_SECTION_ID": "12" }
  ],
  "meta": { "total": 2 }
}
```

## Error response example

403 — no access to the list:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "No permission to view and edit the list."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_IBLOCK_TYPE` | `iblockTypeId` is not in the set `lists`, `bitrix_processes`, `lists_socnet`, `structure` |
| 400 | `INVALID_FILTER` | The `filter` parameter is not valid JSON. An ambiguous envelope is rejected as well: the bracket form and JSON in one request (in either order), two spellings of one condition, or a bracket condition deeper than two levels — half of the conditions are irrecoverably lost during parsing, so the request is refused rather than half-applied. |
| 400 | `INVALID_PARAMS` | `start` or `offset` is not a non-negative integer. Such a value used to be dropped silently, and the page served was not the one asked for |
| 422 | `BITRIX_ERROR` | `filter` names a field that cannot be filtered on. The error text names the field: `Filter field not allowed: <field>` |
| 422 | `BITRIX_ERROR` | Unsupported filter operator. `error.b24Code` is `ERROR_ARGUMENT`, and the message names the operator: `Filter operation not allowed: <operator>` |
| 403 | `BITRIX_ACCESS_DENIED` | No access to the list. As measured on 2026-09-02, a list that does not exist at this address returns `404`, but Bitrix24 also returns this code when permissions are genuinely missing |
| 404 | `LIST_NOT_FOUND` | No list with the given `iblockId` exists. Bitrix24 reports this with a machine code, so an absent list is distinguishable from a permission refusal |
| 409 | `LISTS_MODULE_NOT_ENABLED` | The "Lists" module is not enabled on the portal |
| 403 | `SCOPE_DENIED` | The key lacks the `lists` scope |
| 401 | `TOKEN_MISSING` | The key has no access tokens configured |

For the full list of common API errors, see [Errors](/docs/errors).

## Known specifics

Custom property values arrive under `PROPERTY_<id>` keys as a map from value identifier to value. The same shape is shown in detail in [Get element](./get.md).

## See also

- [Get element](./get.md)
- [Create element](./create.md)
- [Element property files](./files.md)
- [List fields](/docs/lists/fields)
- [Universal lists](/docs/lists)