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

List comments

GET /v1/timelines

Returns timeline comments attached to a specific CRM record. The entityType and entityId filters are required — without them the request returns 400 MISSING_REQUIRED_FILTER.

Parameters

Parameter Type Req. Default Description
filter[entityType] string yes — Type of the parent CRM record: deal, lead, contact, company or DYNAMIC_<entityTypeId> for smart processes (e.g. DYNAMIC_174)
filter[entityId] number yes — Parent record ID. The source depends on the type: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, GET /v1/items/:entityTypeId (smart process items)
limit number no 50 Number of records (up to 5000). When limit > 50 Vibecode automatically requests several pages from Bitrix24
offset number no 0 Skip N records. When offset > 0, limit ≤ 500 is recommended
select string no — Field selection: ?select=id,comment,authorId

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/timelines?filter[entityType]=deal&filter[entityId]=741" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/timelines?filter[entityType]=deal&filter[entityId]=741" \
  -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/timelines?filter[entityType]=deal&filter[entityId]=741', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines?filter[entityType]=deal&filter[entityId]=741', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of comments (all fields — see Comment fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 66309,
      "entityId": 741,
      "entityType": "deal",
      "comment": "First contact: the client showed interest in the offer",
      "authorId": 1,
      "createdAt": "2026-04-24T12:39:28.000Z"
    },
    {
      "id": 66311,
      "entityId": 741,
      "entityType": "deal",
      "comment": "Follow-up: the client is ready to sign the contract next week",
      "authorId": 1,
      "createdAt": "2026-04-24T12:39:30.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Error response example

400 — a required filter was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FILTER",
    "message": "GET /v1/timelines requires filter fields: entityType, entityId. Example: GET /v1/timelines?filter[entityType]=...&filter[entityId]=..."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FILTER The required filter[entityType] and filter[entityId] were not provided
422 BITRIX_ERROR Invalid entityType value (e.g. a numeric CRM code instead of a string)
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens
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.

Known specifics

entityType is a string. Use string identifiers of CRM types: deal, lead, contact, company. For smart processes — DYNAMIC_<entityTypeId> (e.g. DYNAMIC_174). In the response the value comes back in lowercase (dynamic_174). Numeric CRM codes do not work in entityType — the request returns 422 BITRIX_ERROR Access denied.

Filtering only by entityType + entityId. Bitrix24 ignores any additional fields in the filter (authorId, comment, ranges like >=createdAt, etc.) — the response is the same as without them. If you need to narrow results by author or text, fetch all comments for the record and filter them on the client side.

Result order — by id ASC. The list is returned in creation order: the earliest comments first. If you need the reverse order, reverse the array on the client (data.reverse()). Sorting parameters (order[...], sort=) do not apply to this endpoint.

Auto-pagination. When limit > 50 Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response.

See also