Stage history

GET /v1/stage-history

Returns the history of CRM record transitions across stages and statuses — when a record reached each pipeline stage. Used for reports on the velocity of deals, leads and smart-process items and for conversion analysis across pipelines.

Bitrix24 API: crm.stagehistory.list Scope: crm

Parameters

The set of stage filter fields depends on the record type. For the stage-based types deal, invoice, new-invoice and smart processes, stageId, stageSemanticId, categoryId are available. For the status-based type lead, statusId, statusSemanticId are available. A field that does not belong to the type returns 400 INVALID_FILTER_FIELD.

For limit > 50, Vibecode automatically paginates the request on the server side. The maximum is 5000 records per call. The meta.hasMore field shows whether there are records beyond the current selection.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/stage-history?entityType=deal&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/stage-history?entityType=deal&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const params = new URLSearchParams({ entityType: 'deal', limit: '50' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/stage-history?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

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

JavaScript — OAuth application

const params = new URLSearchParams({ entityType: 'deal', limit: '50' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/stage-history?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

The set of record fields depends on the type: the stage-based types (deal, invoice, new-invoice, smart processes) return stageId, stageSemanticId, categoryId, while the status-based type lead returns statusId, statusSemanticId.

Response example

Deal (entityType=deal) — transitions across pipeline stages:

{
  "success": true,
  "data": [
    {
      "id": 12857,
      "typeId": 1,
      "ownerId": 7913,
      "createdAt": "2026-06-24T00:03:50+00:00",
      "categoryId": 9,
      "stageSemanticId": "P",
      "stageId": "C9:NEW"
    },
    {
      "id": 12855,
      "typeId": 1,
      "ownerId": 7911,
      "createdAt": "2026-06-23T00:02:34+00:00",
      "categoryId": 9,
      "stageSemanticId": "P",
      "stageId": "C9:NEW"
    }
  ],
  "meta": {
    "total": 2941,
    "hasMore": true
  }
}

Lead (entityType=lead) — transitions across statuses:

{
  "success": true,
  "data": [
    {
      "id": 3689,
      "typeId": 1,
      "ownerId": 1001083,
      "createdAt": "2026-06-10T18:03:12+00:00",
      "statusId": "NEW",
      "statusSemanticId": "P"
    }
  ],
  "meta": {
    "total": 296,
    "hasMore": true
  }
}

Smart process (entityType=164) — transitions across stages, exactly as for a deal:

{
  "success": true,
  "data": [
    {
      "id": 47,
      "typeId": 1,
      "ownerId": 55,
      "createdAt": "2026-08-04T22:07:23+00:00",
      "categoryId": 27,
      "stageSemanticId": "P",
      "stageId": "DT164_27:NEW"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

Error response example

400 — the filter field does not apply to the record type:

{
  "success": false,
  "error": {
    "code": "INVALID_FILTER_FIELD",
    "message": "\"statusId\" is not a valid filter for entityType \"deal\". entityType \"deal\" is stage-based — use stageId."
  }
}

Errors

Full list of common API errors — Errors.

How to get a smart process `entityTypeId`

The numeric type identifier is returned by GET /v1/smart-processes — the entityTypeId field of each item. It differs from the type id and is not derived from it.

curl "https://vibecode.bitrix24.com/v1/smart-processes" \
  -H "X-Api-Key: YOUR_API_KEY"

Pass the value you get as entityType:

curl "https://vibecode.bitrix24.com/v1/stage-history?entityType=164&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Do not probe for the identifier. Every request carrying a non-existent entityTypeId reaches Bitrix24 and is rejected, and a run of such rejections trips 429 ERROR_LOOP_DETECTED for the key — after which ordinary deal history requests stop going through as well.

Known specifics

Sorting is not configurable. The sort parameter is not accepted — the order of records cannot be changed.

See also

• Deals
• Leads
• Statuses and stages
• Sales pipelines
• Smart processes
• API overview
• Errors