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

List smart process items

GET /v1/items/:entityTypeId

Returns a list of items in the specified smart process with filtering, sorting, and pagination.

Parameters

Parameter Type Default Description
entityTypeId (path) number — Smart process type ID. List: GET /v1/smart-processes
limit number 50 Number of records (up to 5000)
offset number 0 Skip N records. For a full-collection walk a cursor is cheaper — order[id]=asc plus filter[>id] from meta.nextAfterId
order object — Sorting: ?order[createdTime]=desc
select string — Field selection: ?select=id,title,stageId
filter object — Filtering by fields from GET /v1/items/:entityTypeId/fields.
Filtering syntax. Example: ?filter[assignedById]=1
withTotal string — Whether you need the count: true or false. false — do not request a count. This is the only way to guarantee that meta.total is absent from the response. Without the parameter: the API key setting applies, then the platform default — and in that case a short page still carries the exact count even without an explicit request. Paging and counts

Examples

In the examples entityTypeId = 156 — replace it with your smart process ID.

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/items/156?limit=10&order[createdTime]=desc&filter[assignedById]=1" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/items/156?limit=10&order[createdTime]=desc&filter[assignedById]=1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({
  limit: '10',
  'order[createdTime]': 'desc',
  'filter[assignedById]': '1',
})

const res = await fetch(`https://vibecode.bitrix24.com/v1/items/156?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, meta } = await res.json()
console.log(`Found: ${meta.total}`)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({
  limit: '10',
  'order[createdTime]': 'desc',
  'filter[assignedById]': '1',
})

const res = await fetch(`https://vibecode.bitrix24.com/v1/items/156?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Pagination is returned in the meta object (as with all list endpoints on the platform), not at the top level.

Field Type Description
data array Array of items
meta.total number Total number of records. An optional field: if no count was requested, it is absent from the response
meta.hasMore boolean Whether more pages exist
meta.nextAfterId string The identifier of the last returned record. Returned when the sort is strictly id ascending, while hasMore is true. Pass it back as filter[>id] — a cheap replacement for a growing offset
data[].id number Item ID
data[].title string Name
data[].stageId string Stage
data[].categoryId number Pipeline ID
data[].opportunity number Amount
data[].currencyId string Currency
data[].assignedById number Responsible person
data[].createdTime datetime Creation date

The card URL of any item from the data array is built from its id:

https://<portal>.bitrix24.com/crm/type/<entityTypeId>/details/<id>/

<entityTypeId> — the smart process type ID (the same as in the request path). <portal> — the Bitrix24 portal domain. If the smart process is placed in a separate section of your Bitrix24 account, Bitrix24 opens the card at the corresponding path. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 783,
      "title": "Supply contract",
      "stageId": "DT156_41:NEW",
      "categoryId": 41,
      "companyId": 15,
      "contactId": 42,
      "opportunity": 500000,
      "currencyId": "USD",
      "assignedById": 1,
      "createdBy": 1,
      "createdTime": "2026-04-15T14:30:00+00:00",
      "updatedTime": "2026-04-15T14:30:00+00:00"
    }
  ],
  "meta": { "total": 23, "hasMore": true }
}

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens
400 INVALID_DYNAMIC_PARAM entityTypeId is not a positive integer or is reserved (1, 2, 3, 4, 7, 31)
400 UNKNOWN_FILTER_FIELD The filter field does not exist on the entity — the message lists the available fields
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

See also