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 Required Default Description
Parameterfilter.entityType Typestring Requiredyes Default— DescriptionType 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
Parameterfilter.entityId Typenumber Requiredyes Default— DescriptionParent 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)
Parameterlimit Typenumber Requiredno Default50 DescriptionNumber of records (up to 5000)
Parameteroffset Typenumber Requiredno Default0 DescriptionSkip N records
Parameterselect Typestring[] Requiredno Default— DescriptionField 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of comments (all fields — see Comment fields)
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Page through the results using meta.hasMore: a data length equal to limit does not rule out the last page.

Response example

The request includes 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
HTTP400 CodeMISSING_REQUIRED_FILTER DescriptionThe required filter.entityType and filter.entityId were not provided
HTTP422 CodeBITRIX_ERROR DescriptionInvalid entityType value (e.g. a numeric CRM code instead of a string)
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

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