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

Search comments

POST /v1/timelines/search

Search timeline comments with a filter passed in the request body — a unified interface with the other entities. A filter by entityType and entityId is required: without them the request returns 400 MISSING_REQUIRED_FILTER. For a simple selection within the context of a single record, GET /v1/timelines with a query filter works as well.

Request fields (body)

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). Get the entityTypeId value from GET /v1/smart-processes
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)
offset number no 0 Skip N records
select string[] no — Field selection: ["id", "comment", "authorId"]

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/timelines/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityType": "deal", "entityId": 575 },
    "select": ["id", "comment", "authorId"],
    "limit": 3
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/timelines/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityType": "deal", "entityId": 575 },
    "select": ["id", "comment", "authorId"],
    "limit": 3
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/timelines/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityType: 'deal', entityId: 575 },
    select: ['id', 'comment', 'authorId'],
    limit: 3,
  }),
})

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/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityType: 'deal', entityId: 575 },
    select: ['id', 'comment', 'authorId'],
    limit: 3,
  }),
})

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
meta.durationMs number Request duration in milliseconds

The meta fields sit next to data, not inside it. Pages must be walked by meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

The request passed select, so the response contains only the selected fields.

JSON 
{
  "success": true,
  "data": [
    {
      "id": 67119,
      "comment": "First contact: the client showed interest in the offer",
      "authorId": 1
    },
    {
      "id": 67121,
      "comment": "Follow-up: the client is ready to sign the contract next week",
      "authorId": 1
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "durationMs": 1208
  }
}

Error response example

400 — a required filter was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FILTER",
    "message": "POST /v1/timelines/search requires filter fields: entityType, entityId. Example body: { \"filter\": {\"entityType\":\"...\",\"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

Full list of common API errors — Errors.

Known specifics

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

Result order — by id ASC. The list is returned in creation order: the earliest comments first. Sorting parameters (order, sort) do not apply to this endpoint.

See also