# crm.stagehistory.list

URL: https://chugunov.pro/api-bitrix24/crm/crm-stage-history-list/
Проверено на Битрикс24 REST API, обновлено 11.09.2026 (ревизия источника fb39d6c).
Источник: официальная документация Битрикс24 (bitrix-tools/b24-rest-docs, лицензия MIT, © Bitrix). Справочник независимый, официальной документацией не является.

Получить историю движения по стадиям
Scope: `crm`
Кто может выполнять метод: любой пользователь

## Описание

Метод `crm.stagehistory.list` возвращает записи об истории движения по стадиям для элементов:
- [лидов](https://chugunov.pro/api-bitrix24/crm/leads/),
- [сделок](https://chugunov.pro/api-bitrix24/crm/deals/),
- [старых счетов](https://chugunov.pro/api-bitrix24/crm/outdated/invoice/),
- [новых счетов](https://apidocs.bitrix24.ru/api-reference/crm/universal/invoice.html),
- [смарт-процессов](https://chugunov.pro/api-bitrix24/crm/universal/user-defined-object-types/).

## Параметры

- `entityTypeId` `integer` — необязательный. Идентификатор типа объекта. Может принимать значения:
  - `1` — лид,
  - `2` — сделка,
  - `5` — счет (старый),
  - `31` - счет (новый),
  - числовой идентификатор [пользовательского типа](https://chugunov.pro/api-bitrix24/crm/universal/user-defined-object-types/#id), например `130`
- `order` `object` — необязательный. Список для сортировки, где ключ — поле, а значение — `ASC` или `DESC`
- `filter` `object` — необязательный. Список для фильтрации. Фильтр поддерживает использование точных значений, массивов значений, а также модификаторы:
  - `>=` — больше либо равно
  - `>` — больше
  - `<=` — меньше либо равно
  - `<` — меньше
  - `@` — IN, в качестве значения передается массив
  - `!@` — NOT IN, в качестве значения передается массив
  - `%` — LIKE, поиск по подстроке. Символ `%` в значении фильтра передавать не нужно. Поиск ищет подстроку в любой позиции строки
  - `=%` — LIKE, поиск по подстроке. Символ `%` нужно передавать в значении. Примеры:
  	- `"мол%"` — ищет значения, начинающиеся с «мол»
  	- `"%мол"` — ищет значения, заканчивающиеся на «мол»
  	- `"%мол%"` — ищет значения, где «мол» может быть в любой позиции
  - `%=` — LIKE (аналогично `=%`)
  - `!%` — NOT LIKE, поиск по подстроке. Символ `%` в значении фильтра передавать не нужно. Поиск идет с обеих сторон
  - `!=%` — NOT LIKE, поиск по подстроке. Символ `%` нужно передавать в значении. Примеры:
  	- `"мол%"` — ищет значения, не начинающиеся с «мол»
  	- `"%мол"` — ищет значения, не заканчивающиеся на «мол»
  	- `"%мол%"` — ищет значения, где подстроки «мол» нет в любой позиции
  - `!%=` — NOT LIKE (аналогично `!=%`)
  - `=` — равно, точное совпадение (используется по умолчанию)
  - `!=` — не равно
  - `!` — не равно
- `select` `object` — необязательный. Список получаемых полей
- `start` `integer` — необязательный. Сдвиг для постраничной навигации. Логика работы с постраничной навигацией стандартная для [списочных методов](https://apidocs.bitrix24.ru/settings/how-to-call-rest-api/list-methods-pecularities.html)

## Ответ

HTTP-статус: 200

```json
{
    "result": {
        "items": [
        {
            "ID": 35,
            "TYPE_ID": 1,
            "OWNER_ID": 21,
            "CREATED_TIME": "2024-04-25T14:59:11+00:00",
            "CATEGORY_ID": 0,
            "STAGE_SEMANTIC_ID": "P",
            "STAGE_ID": "NEW"
        }
        ]
    },
    "total": 1,
    "time": {
        "start": 1724106224.858572,
        "finish": 1724106225.344968,
        "duration": 0.48639607429504395,
        "processing": 0.11864185333251953,
        "date_start": "2024-08-15T22:15:44+00:00",
        "date_finish": "2024-08-15T22:15:45+00:00",
        "operating": 0.11855506896972656
    }
}
```

### Возвращаемые данные

- `result` `array`. Корневой элемент ответа, содержит массив записей [items](#items). Каждый объект — массив с ключами
- `time` `time`. Информация о времени выполнения запроса

## Ошибки

HTTP-статус: 401

```json
{
    "error": 0,
    "error_description": "SHIPMENT_DOCUMENT entity is not supported"
}
```

- `403` — `allowed_only_intranet_user`. Действие разрешено только интранет-пользователям
- `400` — `ENTITY_TYPE_NOT_SUPPORTED`. Entity type `TYPE` is not supported
- `400` — `INVALID_ARG_VALUE`. Invalid filter: field '`field`' is not allowed in filter
- `400` — `INVALID_ARG_VALUE`. Invalid filter: field '`field`' has invalid value
- `400` — `INVALID_ARG_VALUE`. Invalid order: field '`field`' is not allowed in order
- `400` — `INVALID_ARG_VALUE`. Invalid order: allowed sort directions are `ASC, DESC`. But got '`orderValue`' for field '`field`'

## Примеры запроса

### cURL (Webhook)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":2,"order":{"ID":"ASC"},"filter":{"OWNER_ID":1},"select":["ID","STAGE_ID","CREATED_TIME"]}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.stagehistory.list
```

### cURL (OAuth)

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":2,"order":{"ID":"ASC"},"filter":{"OWNER_ID":1},"select":["ID","STAGE_ID","CREATED_TIME"],"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.stagehistory.list
```

### JS

```js
// callListMethod: Получает все данные сразу. Используйте только для небольших выборок (< 1000 элементов) из-за высокой нагрузки на память.

const parameters = {
    entityTypeId: 2,
    order: { "ID": "ASC" },
    filter: { "OWNER_ID": 1 },
    select: [ "ID", "STAGE_ID", "CREATED_TIME" ]
};

try {
  const response = await $b24.callListMethod(
    'crm.stagehistory.list',
    parameters,
    (progress) => { console.log('Progress:', progress) }
  )
  const items = response.getData() || []
  for (const entity of items) { console.log('Entity:', entity) }
} catch (error) {
  console.error('Request failed', error)
}

// fetchListMethod: Выбирает данные по частям с помощью итератора. Используйте для больших объемов данных для эффективного потребления памяти.

try {
  const generator = $b24.fetchListMethod('crm.stagehistory.list', parameters, 'ID')
  for await (const page of generator) {
    for (const entity of page) { console.log('Entity:', entity) }
  }
} catch (error) {
  console.error('Request failed', error)
}

// callMethod: Ручное управление постраничной навигацией через параметр start. Используйте для точного контроля над пакетами запросов. Для больших данных менее эффективен, чем fetchListMethod.

try {
  const response = await $b24.callMethod('crm.stagehistory.list', parameters, 0)
  const result = response.getData().result || []
  for (const entity of result) { console.log('Entity:', entity) }
} catch (error) {
  console.error('Request failed', error)
}
```

### Python

```python
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.stagehistory.list(
        entity_type_id=2,
        order={
            "ID": "ASC",
        },
        filter={
            "OWNER_ID": 1,
        },
        select=[
            "ID",
            "STAGE_ID",
            "CREATED_TIME",
        ],
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.stagehistory.list(
        entity_type_id=2,
        order={
            "ID": "ASC",
        },
        filter={
            "OWNER_ID": 1,
        },
        select=[
            "ID",
            "STAGE_ID",
            "CREATED_TIME",
        ],
    ).as_list().response
    result = bitrix_response.result
    for item in result:
        print(item)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.stagehistory.list(
        entity_type_id=2,
        order={
            "ID": "ASC",
        },
        filter={
            "OWNER_ID": 1,
        },
        select=[
            "ID",
            "STAGE_ID",
            "CREATED_TIME",
        ],
    ).as_list_fast(descending=True).response
    result = bitrix_response.result
    for item in result:
        print(item)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
```

### PHP

```php
try {
    $response = $b24Service
        ->core
        ->call(
            'crm.stagehistory.list',
            [
                'entityTypeId' => 2,
                'order' => ['ID' => 'ASC'],
                'filter' => ['OWNER_ID' => 1],
                'select' => ['ID', 'STAGE_ID', 'CREATED_TIME'],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
    
    if ($result->more()) {
        $result->next();
    }

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error listing stage history: ' . $e->getMessage();
}
```

### BX24.js

```js
BX24.callMethod(
    "crm.stagehistory.list",
    {
        entityTypeId: 2,
        order: { "ID": "ASC" },
        filter: { "OWNER_ID": 1 },
        select: [ "ID", "STAGE_ID", "CREATED_TIME" ]
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
        {
            console.dir(result.data());
            if(result.more())
                result.next();
        }
    }
);
```

### PHP CRest

```php
require_once('crest.php');

$result = CRest::call(
    'crm.stagehistory.list',
    [
        'entityTypeId' => 2,
        'order' => ['ID' => 'ASC'],
        'filter' => ['OWNER_ID' => 1],
        'select' => ['ID', 'STAGE_ID', 'CREATED_TIME']
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
```

### Go

```go
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.stagehistory.list", b24.Params{
	"entityTypeId": 2,
	"order": b24.Params{
		"ID": "ASC",
	},
	"filter": b24.Params{
		"OWNER_ID": 1,
	},
	"select": []string{"ID", "STAGE_ID", "CREATED_TIME"},
}, b24.WithIdempotent())
if err != nil {
	return fmt.Errorf("crm.stagehistory.list: %w", err)
}

// Метод заворачивает ответ в объект с ключом "items".
raw, ok := b24.Unwrap(res.Result, "items")
if !ok {
	return fmt.Errorf("в ответе нет ключа items")
}

var items []struct {
	ID              b24.ID `json:"ID"`
	TypeID          b24.ID `json:"TYPE_ID"`
	OwnerID         b24.ID `json:"OWNER_ID"`
	CreatedTime     string `json:"CREATED_TIME"`
	CategoryID      b24.ID `json:"CATEGORY_ID"`
	StageSemanticID string `json:"STAGE_SEMANTIC_ID"`
}
if err := json.Unmarshal(raw, &items); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
for _, it := range items {
	fmt.Println(it.ID)
}
```

Оригинал в официальной документации: https://apidocs.bitrix24.ru/api-reference/crm/crm-stage-history-list.html