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

filter[entityType] is the type of the parent CRM record: deal, lead, contact, company or DYNAMIC_<entityTypeId> for smart processes, for example DYNAMIC_174. The entityTypeId value comes from GET /v1/smart-processes. filter[entityId] is the parent record ID, and its source depends on the type: GET /v1/deals, GET /v1/leads, GET /v1/contacts, GET /v1/companies, and for smart process items — GET /v1/items/:entityTypeId.

Examples

curl — personal key

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

curl — OAuth application

curl -g "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

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

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

Response example

{
  "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:

{
  "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

For the full list of common API errors, see Errors.

Known specifics

entityType is a string. Use string CRM type identifiers: 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. Other comment fields in the filter (authorId, comment, ranges like >=createdAt, etc.) are accepted without an error but do not narrow the selection — 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.

Default order — ascending by id. Without sort, the list is returned in creation order: the earliest comments first. For the newest first, use sort=-createdAt.

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

See also

• Get comment
• Add comment
• Comment fields
• Filtering syntax
• Entity API
• Batch
• Limits and optimization