keys."> keys."> keys.">

For AI agents: markdown of this page — /docs-content-en/lists/elements.md documentation index — /llms.txt

Elements

Work with list rows: retrieve elements with filtering, create, update, and delete them, and get links to files from element properties. Custom property values are addressed by PROPERTY_<id> keys.

Bitrix24 API: lists.element.* Scope: lists

List elements

GET /v1/lists/:iblockId/elements

Returns list elements with filtering and pagination.

Parameters

Parameter Type Required Default Description
ParameteriblockId (path) Typestring Requiredyes Default— DescriptionNumeric list identifier IBLOCK_ID or symbolic code IBLOCK_CODE
ParameteriblockTypeId (query) Typestring Requiredno Defaultlists DescriptionInfoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows
structure — company-structure type (holds the built-in absence-calendar iblock absence)
Parameterfilter (query) Typestring Requiredno Default— DescriptionJSON 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.
Parameterselect (query) Typestring Requiredno Default— DescriptionComma-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
Parameterstart (query) Typenumber Requiredno Default0 DescriptionPage offset in steps of 50. Bitrix24 rounds start down to a multiple of 50
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionAlias 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

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

curl — OAuth application

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of list elements
Fielddata[].ID Typestring DescriptionElement identifier
Fielddata[].NAME Typestring DescriptionElement name
Fielddata[].IBLOCK_SECTION_ID Typestring or null DescriptionSection identifier, null for an element outside sections
Fielddata[].PROPERTY_<id> Typeobject DescriptionCustom property values. Key is the property identifier from List fields. The value shape is described in the "Known specifics" section
Fieldmeta.total Typenumber DescriptionTotal number of elements matching the filter
Fieldmeta.next Typenumber DescriptionOffset 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.

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
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not in the set lists, bitrix_processes, lists_socnet, structure
HTTP400 CodeINVALID_FILTER DescriptionThe 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.
HTTP400 CodeINVALID_PARAMS Descriptionstart 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
HTTP422 CodeBITRIX_ERROR Descriptionfilter names a field that cannot be filtered on. The error text names the field: Filter field not allowed: <field>
HTTP422 CodeBITRIX_ERROR DescriptionUnsupported filter operator. error.b24Code is ERROR_ARGUMENT, and the message names the operator: Filter operation not allowed: <operator>
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo 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
HTTP404 CodeLIST_NOT_FOUND DescriptionNo list with the given iblockId exists. Bitrix24 reports this with a machine code, so an absent list is distinguishable from a permission refusal
HTTP409 CodeLISTS_MODULE_NOT_ENABLED DescriptionThe "Lists" module is not enabled on the portal
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no access tokens configured

For the full list of common API errors, see 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.

See also