---
title: "FetchListV2.make"
description: "Returns an AsyncGenerator that allows processing data from list methods of Bitrix24 REST API version 2 as it is received without loading the entire array into memory at once. This is especially useful when working with very large volumes of data."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/working-with-the-rest-api/fetch-list-rest-api-ver2"
last_updated: "2026-05-08"
---
# FetchListV2.make

> Returns an AsyncGenerator that allows processing data from list methods of Bitrix24 REST API version 2 as it is received without loading the entire array into memory at once. This is especially useful when working with very large volumes of data.

> [!WARNING]
> We are still updating this page. Some data may be missing here — we will complete it shortly.

> [!CAUTION]
> **Bitrix24 is gradually transitioning to REST API version 3**.
> - When calling methods [available in REST API v3](https://apidocs.bitrix24.com/api-reference/rest-v3/index.html), the method automatically logs a warning.

## Overview

When you need to process large volumes of data from list methods of REST API version 2 in parts (chunks), use `FetchListV2.make()`.

This method implements a fast algorithm for iterating over large data sets without loading all data into memory at once. Each iteration returns the next page/batch of results until all data is received.

```ts
// Basic usage
import { EnumCrmEntityTypeId } from '@bitrix24/b24jssdk'

const generator = $b24.actions.v2.fetchList.make({
  method: 'crm.item.list',
  params: {
    entityTypeId: EnumCrmEntityTypeId.deal,
    filter: { '>opportunity': 10000 }
  },
  idKey: 'id',
  customKeyForResult: 'items',
  requestId: 'unique-request-id'
})

for await (const chunk of generator) {
  // Process chunk (e.g., save to database, analyze, etc.)
  console.log(`Processing ${chunk.length} items`)
}
```

### When to Use FetchListV2.make()

1. **Very large data volumes**: When the number of records is in the thousands or tens of thousands.
2. **Stream processing**: When data needs to be processed as it arrives.
3. **Long operations**: When processing each record requires significant time.

## Method Signature

```ts-type
make<T = unknown>(
  options: ActionFetchListV2
): AsyncGenerator<T[]>
```

### Parameters

The `options` object contains the following properties:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| **`method`** | `string` | Yes | REST API method name that returns a data list (e.g., `crm.contact.list` , `tasks.task.list` ). |
| **`params`** | `OmitTypeCallParams,'start'|'order'>` | No | Request parameters, excluding the `start` and `order` parameters. The `start` parameter is reserved because the method retrieves all data in a single call. The `order` parameter is reserved because cursor-based pagination requires sorting strictly by `idKey` ascending — see Limitations . Use `filter` and `select` to control the selection. |
| **`idKey`** | `string` | No | Name of the field containing the unique element identifier. Default: `'ID'` (uppercase). Can also be `'id'` (lowercase) or another field depending on the REST API data structure. |
| **`customKeyForResult`** | `string` | No | Custom key indicating that the REST API response will be selected by this field. For example: `items` for a list of CRM elements. |
| **`requestId`** | `string` | No | Unique request identifier for tracking. Used for request deduplication and debugging. |

### Return Value

`AsyncGenerator<T[]>` — an asynchronous generator that returns data chunks as arrays of type `T`.

Each iteration of the generator returns:

- An array of elements (chunk) with up to `50` records.
- The generator completes when all data is received.

## Key Concepts

### Automatic Warning

When calling methods that **are available in REST API version 3**, the system automatically logs a warning:

```json
"The method {method_name} is available in restApi:v3. It's worth migrating to the new API."
```

This indicates that you should consider migrating to the newer REST API version.

### AsyncGenerator vs Promise

Unlike `CallListV2.make()`, which returns a `Promise` with all data at once, `FetchListV2.make()` returns an asynchronous generator:

| Aspect | `CallListV2.make()` | `FetchListV2.make()` |
| --- | --- | --- |
| **Return Value** | `Promise>` | `AsyncGenerator` |
| **Memory** | Loads all data into memory | Processes data in parts |
| **Usage** | `awaitresponse.getData()` | `forawait(constchunkofgenerator)` |
| **Suitable for** | Small to medium data volumes | Very large data volumes |

### Performance Optimization

The method implements the [Bitrix24 recommended algorithm](https://apidocs.bitrix24.com/settings/performance/huge-data.html) for efficient work with large data volumes:

1. `start: -1`: Disables counting the total number of records, significantly speeding up query execution.
2. **Filtering by increasing ID**: Each subsequent query uses a `>ID` filter with the ID of the last retrieved element.
3. **Stream processing**: Data is processed as it is received, saving memory.
4. **Automatic data end detection**: Requests stop when an empty array is received or the number of elements is less than the page size (`50`).

### REST API v2 Response Structure

In REST API version 2, various methods may return data in different structures:

- **Direct array**: `{ result: [...] }`
- **Grouped array**: `{ result: { items: [...] } }`

The `customKeyForResult` parameter allows you to specify the key where the data is located in the response.

### Limitations

- **Page size**: Fixed limitation of Bitrix24 REST API version 2 — `50` records per request.
- **Sorting is fixed**: The method always sorts by `idKey` ascending, because cursor pagination relies on `>idKey` to walk the dataset. A user-supplied `order` value would break that invariant, so the type signature excludes `order` and any value passed at runtime is stripped with a `warning` log entry. To narrow the result set, use `filter` instead.
- **Only for list methods**: Intended only for methods that return data arrays.

## Error Handling

Since the method returns an asynchronous generator, errors are handled differently than in `CallListV2.make()`:

```ts
try {
  const generator = $b24.actions.v2.fetchList.make({
    method: 'some.method',
    params: { /* some_params */ },
    idKey: 'id',
    customKeyForResult: 'items',
    requestId: 'unique-request-id'
  })

  for await (const chunk of generator) {
    // Process chunk (e.g., save to database, analyze, etc.)
    console.log(`Processing ${chunk.length} items`)
  }
} catch (error) {
  // Handling error
  if (
    error instanceof SdkError
    && error.code === 'JSSDK_CORE_B24_FETCH_LIST_METHOD_API_V2'
  ) {
    console.error(`${error.message}`, { code: error.code })
  } else {
    console.error('Some error', error)
  }
}
```

## Examples

### Step-by-step processing of a large number of companies

```ts [ProcessCrmItems.ts]
import { B24Hook, EnumCrmEntityTypeId, LoggerFactory, Text, SdkError, AjaxError } from '@bitrix24/b24jssdk'

type Company = {
  id: number
  title: string
}

const devMode = typeof import.meta !== 'undefined' && (import.meta.dev || import.meta.env?.DEV)
const $logger = LoggerFactory.createForBrowser('Example:ProcessCrmItems', devMode)
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

async function processCrmItemList(): Promise<void> {
  let batchNumber = 0
  let totalItems = 0

  const sixMonthAgo = new Date()
  sixMonthAgo.setMonth((new Date()).getMonth() - 6)
  sixMonthAgo.setHours(0, 0, 0)
  
  const requestId = 'some-crm-item-list'
  
  try {
    const generator = $b24.actions.v2.fetchList.make<Company>({
      method: 'crm.item.list',
      params: {
        entityTypeId: EnumCrmEntityTypeId.company,
        filter: {
          // use some filter by title
          '=%title': 'Prime%',
          '>=createdTime': Text.toB24Format(sixMonthAgo) // created at least 6 months ago
        },
        select: ['id', 'title']
      },
      idKey: 'id',
      customKeyForResult: 'items',
      requestId
    })
    
    for await (const chunk of generator) {
      batchNumber++
      totalItems += chunk.length

      $logger.info(`Processing batch #${batchNumber}`, {
        batchSize: chunk.length,
        totalSoFar: totalItems
      })
      
      // Example: saving to database
      await saveToDatabase(chunk)
      
      // Example: sending to message queue
      await sendToMessageQueue(chunk)
    }
    
    $logger.notice(`Processed ${totalItems} elements in ${batchNumber} batches`)
  } catch (error) {
    if (error instanceof SdkError) {
      $logger.error(`Processing error: ${error.message}`, {
        code: error.code,
        batchNumber,
        totalItems
      })
    } else {
      $logger.error('Unknown error', { error, batchNumber, totalItems })
    }
    throw error
  }
}

// Helper functions
// Database save implementation
async function saveToDatabase(items: Company[]): Promise<void> {
  await new Promise(resolve => setTimeout(resolve, 100)) // Simulation
}

// Message queue send implementation
async function sendToMessageQueue(items: Company[]): Promise<void> {
  await new Promise(resolve => setTimeout(resolve, 50)) // Simulation
}

// Usage
try {
  await processCrmItemList()
} catch (error) {
  $logger.critical('A problem occurred', { error })
}
```

## Alternatives and Recommendations

- **Chunk size**: Bitrix24 REST API version 2 always returns up to 50 records per request.
- **Optimal concurrency**: When processing data from the generator, limited concurrency (3-5 simultaneous operations) is recommended.
- **Error handling**: Always handle errors inside the `for await...of` loop to prevent the entire process from stopping.
- **Progress monitoring**: Implement progress logging for long-running operations.
- **For sequential requests**: Use [`Call`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/call-rest-api-ver2.md) for single calls.
- **For batch operations:** Use [`Batch`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/batch-rest-api-ver2.md) to execute up to 50 commands in a single request.
- **On the client-side (browser):** Use the built-in [`B24Frame`](https://bitrix24.github.io/b24jssdk/raw/docs/getting-started/installation/vue.md#init) object.

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.