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

The method is rolling out in update crm 26.2000.0. It is not available on every Bitrix24 account. If the method is not yet available on your account, the API returns 422 METHOD_NOT_YET_AVAILABLE — this indicates that the update has not reached the account yet, rather than an integration error.

List analytics traces

GET /v1/crm-traces

Lists visit traces linked to one CRM record to help analyze the sources of customer inquiries.

This operation requires the crm-tracking-v3 flag and the REST v3 analytics capability enabled in the Bitrix24 account. The key needs the crm scope.

A READONLY key can read this resource.

Parameters

Parameter Type Required Default Description
ParameterentityType (query) Typestring Requiredyes Default— DescriptionRecord type: LEAD, DEAL, CONTACT, COMPANY, QUOTE.
ParameterentityId (query) Typenumber Requiredyes Default— DescriptionPositive record ID of the selected type. Use the lists of leads, deals, contacts, companies, or quotes.
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionPage size, from 1 to 500.
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionNumber of records to skip before the page. A nonnegative integer.

Pagination: one request reads one page. Increase offset by limit for the next page. No total count or next-page indicator is returned. The filter, select and sort parameters are not accepted.

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/crm-traces?entityType=DEAL&entityId=11&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/crm-traces?entityType=DEAL&entityId=11&limit=50&offset=0" \
  -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/crm-traces?entityType=DEAL&entityId=11&limit=50&offset=0', {
  "method": "GET",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY"
  }
})
const result = await res.json()
console.log(result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-traces?entityType=DEAL&entityId=11&limit=50&offset=0', {
  "method": "GET",
  "headers": {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN"
  }
})
const result = await res.json()
console.log(result)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue
Fielddata Typearray DescriptionVisit traces.
Fielddata[].id Typenumber DescriptionTrace ID.
Fielddata[].sourceId Typenumber or null DescriptionAnalytics source ID.
Fielddata[].createdTime Typestring DescriptionCreation time, ISO 8601.
Fielddata[].isMobile Typeboolean DescriptionWhether the visit used a mobile device.
Fielddata[].channels Typearray DescriptionChannels with code, value fields. Text can be null.
Fielddata[].pages Typearray DescriptionPages with url, title, time fields. Time is ISO 8601. Text can be null.
Fielddata[].utm Typeobject or null DescriptionTags source, medium, campaign, content, term, each a string or null.
Fieldmeta.limit Typenumber DescriptionRequested page size.
Fieldmeta.offset Typenumber DescriptionRequested offset.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "sourceId": 2,
      "createdTime": "2026-10-28T11:59:18+00:00",
      "isMobile": false,
      "channels": [
        {
          "code": "form",
          "value": "5"
        }
      ],
      "pages": [
        {
          "url": "https://example.com/p",
          "title": "VIBE-PROBE page",
          "time": "2026-10-28T10:00:00+00:00"
        }
      ],
      "utm": {
        "source": "vibeprobe",
        "medium": null,
        "campaign": "x",
        "content": null,
        "term": null
      }
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0
  }
}

Error response example

400: required filter missing.

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "entityType and entityId are required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionRequired request fields are missing.
HTTP400 CodeINVALID_PARAMS DescriptionInvalid request type or shape, or an invalid ID.
HTTP403 CodeSCOPE_DENIED DescriptionMissing crm scope.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe platform flag is off or RestV3Tracking is not enabled on the Bitrix24 account. error.release is crm 26.2000.0.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionInvalid Bitrix24 response.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionAn unsupported query parameter was supplied.
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe CRM record is missing or cannot be read.
HTTP403 CodeBITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION DescriptionInsufficient permissions for linked CRM records.

Other Bitrix24 refusal codes, statuses and messages are preserved. See Errors for common failures.

Known specifics

Credential fragments in text fields are redacted. Page addresses without sensitive data are preserved unchanged.

See also