## Session search

> **The method ships in the `imopenlines 26.700.0` update and is not yet available on all Bitrix24 accounts.** If the update has not reached your Bitrix24 account yet, the API returns `422 METHOD_NOT_YET_AVAILABLE` — this means the method has not been released on the account yet, not that the integration is broken.

`POST /v1/openlines/sessions/search`

A list of Open Channel sessions with filters and pagination — the main method for detailed reports and export to external analytics systems. An empty body `{}` returns the first page of all visible sessions.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `configId` | number | no | Open Channel identifier. Source: [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `configIdList` | number[] | no | List of Open Channel identifiers. Source: [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `operatorId` | number | no | Operator identifier. Source: [`GET /v1/users`](/docs/entities/users) |
| `operatorIdList` | number[] | no | List of operator identifiers. Source: [`GET /v1/users`](/docs/entities/users) |
| `source` | string | no | Connector code, for example `livechat`. Values: the `sessions[].source` field in this method's response or `sessionsBySource[].source` in the [`POST /v1/openlines/stats`](/docs/openlines/stats) response |
| `sourceList` | string[] | no | List of connector codes |
| `status` | string | no | Session status: `new` / `answered` / `closed` / `spam` / `paused` |
| `closeReason` | string | no | Close reason: `operator` / `auto` / `spam` / `client` / `replyLimit` |
| `dateCreateFrom` | string | no | Start of the creation period, ISO 8601. The `dateCreateFrom`..`dateCreateTo` period must not exceed 1 year |
| `dateCreateTo` | string | no | End of the creation period, ISO 8601 |
| `dateCloseFrom` | string | no | Start of the closing period, ISO 8601 |
| `dateCloseTo` | string | no | End of the closing period, ISO 8601 |
| `vote` | string | no | Client rating: `like` / `dislike` / `none` / `any` |
| `hasVoteHead` | string | no | Whether there is a supervisor rating: `Y` / `N` |
| `kpiFirstAnswer` | string | no | Whether the first-answer time target (SLA) was met: `Y` / `N`. Requires a bounded period (`dateCreateFrom`+`dateCreateTo` or `dateCloseFrom`+`dateCloseTo`) |
| `hasCrm` | string | no | Whether there is a CRM binding: `Y` / `N` |
| `waitAnswerFrom` | number | no | Min. time to first answer, seconds |
| `waitAnswerTo` | number | no | Max. time to first answer, seconds |
| `waitCloseFrom` | number | no | Min. time to close, seconds |
| `waitCloseTo` | number | no | Max. time to close, seconds |
| `order` | string | no | Sort field: `dateCreate` / `dateClose` / `waitAnswer` / `waitClose` (default `dateCreate`) |
| `orderDirection` | string | no | Direction: `asc` / `desc` (default `desc`) |
| `limit` | number | no | Page size, 1..200 (default 50). An out-of-range value does not cause an error — a page of 50 records is returned |
| `offset` | number | no | Pagination offset (default 0) |

The `status` and `closeReason` filters are mutually exclusive: `closeReason` already implies a closed session. The `hasVoteHead` filter applies only to Open Channels where the user has the supervisor rating permission.

There is no filter by CRM entity type — for CRM only the `hasCrm` flag is available (whether a binding exists). To select a specific type, filter on your side by the `crmEntityType` / `crmEntityId` fields from the response.

**Pagination.** The next page is the same request with `offset` increased by `limit`, while `data.hasNextPage` is `true`. When exporting page by page, pin the upper bound of the period — set `dateCreateTo` to the moment the export starts. Without a fixed bound, new sessions arriving during the export shift the pages, and records at page boundaries may repeat or go missing.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/sessions/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": 1,
    "status": "closed",
    "dateCreateFrom": "2024-05-01T00:00:00+00:00",
    "dateCreateTo": "2024-05-31T23:59:59+00:00",
    "limit": 2
  }'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/sessions/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": 1,
    "status": "closed",
    "dateCreateFrom": "2024-05-01T00:00:00+00:00",
    "dateCreateTo": "2024-05-31T23:59:59+00:00",
    "limit": 2
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configId: 1,
    status: 'closed',
    dateCreateFrom: '2024-05-01T00:00:00+00:00',
    dateCreateTo: '2024-05-31T23:59:59+00:00',
    limit: 2,
  }),
})
const { data } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configId: 1,
    status: 'closed',
    dateCreateFrom: '2024-05-01T00:00:00+00:00',
    dateCreateTo: '2024-05-31T23:59:59+00:00',
    limit: 2,
  }),
})
const { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful response |
| `data.sessions` | array | Sessions of the current page. An empty array if nothing matches the filters |
| `data.sessions[].id` | number | Session identifier |
| `data.sessions[].configId` | number | Open Channel identifier. Open Channel details: [`GET /v1/openline-configs/:id`](/docs/openlines/config/get) |
| `data.sessions[].source` | string | Connector code |
| `data.sessions[].operatorId` | number \| null | Identifier of the operator who finished the session. Employee: [`GET /v1/users`](/docs/entities/users) |
| `data.sessions[].userId` | number | Internal client identifier |
| `data.sessions[].userCode` | string | External client code in the connector |
| `data.sessions[].chatId` | number | Open Channel chat identifier. One chat goes through several sessions |
| `data.sessions[].dateCreate` | string | Session creation date, ISO 8601 |
| `data.sessions[].dateClose` | string \| null | Session closing date, ISO 8601 |
| `data.sessions[].dateFirstAnswer` | string \| null | First answer date, ISO 8601 |
| `data.sessions[].dateOperatorAnswer` | string \| null | Date when the operator started working on the session, ISO 8601. This is a different moment from `dateFirstAnswer` |
| `data.sessions[].status` | string | Status: `new` / `answered` / `closed` / `spam` / `paused` |
| `data.sessions[].closeReason` | string \| null | Close reason: `operator` / `auto` / `spam` / `client` / `replyLimit` |
| `data.sessions[].vote` | string | Client rating: `like` / `dislike` / `none` |
| `data.sessions[].voteHead` | number \| null | Supervisor rating. `null` if there is no rating or the user has no supervisor rating permission |
| `data.sessions[].commentHead` | string \| null | Supervisor comment. `null` in the same cases as `voteHead` |
| `data.sessions[].crmEntityType` | string \| null | Type of the bound CRM entity, for example `lead` or `deal`. `null` if there is no binding or no read permission on the bound entity |
| `data.sessions[].crmEntityId` | number \| null | Identifier of the bound CRM entity. To get the record, use the endpoint for its `crmEntityType`: lead [`GET /v1/leads/:id`](/docs/entities/leads/get), deal [`GET /v1/deals/:id`](/docs/entities/deals/get), contact [`GET /v1/contacts/:id`](/docs/entities/contacts/get), company [`GET /v1/companies/:id`](/docs/entities/companies/get) |
| `data.sessions[].queueTransfers` | number | Number of reassignments in the queue. The reassignments themselves: [Reassignment history](/docs/openlines/sessions/transfers) |
| `data.sessions[].waitAnswer` | number \| null | Time to first answer, seconds. A stored metric — do not compute it from the dates above, the values may differ |
| `data.sessions[].waitClose` | number \| null | Time to close, seconds. A stored metric, like `waitAnswer` |
| `data.sessions[].kpiFirstAnswer` | boolean \| null | Whether the first-answer time target was met |
| `data.sessions[].messageCount` | number | Number of messages in the session |
| `data.hasNextPage` | boolean | Whether there is a next page |

## Response example

```json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 781,
        "configId": 1,
        "source": "livechat",
        "operatorId": 29,
        "userId": 1211,
        "userCode": "livechat|1|2073|1211",
        "chatId": 2075,
        "dateCreate": "2024-05-13T15:08:33+00:00",
        "dateClose": "2024-06-13T15:46:31+00:00",
        "dateFirstAnswer": "2024-05-13T15:12:05+00:00",
        "dateOperatorAnswer": "2024-05-13T15:09:14+00:00",
        "status": "closed",
        "closeReason": "operator",
        "vote": "like",
        "voteHead": null,
        "commentHead": null,
        "crmEntityType": "contact",
        "crmEntityId": 2399,
        "queueTransfers": 0,
        "waitAnswer": 212,
        "waitClose": 116,
        "kpiFirstAnswer": false,
        "messageCount": 5
      },
      {
        "id": 779,
        "configId": 1,
        "source": "livechat",
        "operatorId": 29,
        "userId": 1209,
        "userCode": "livechat|1|2069|1209",
        "chatId": 2071,
        "dateCreate": "2024-05-13T15:05:52+00:00",
        "dateClose": "2024-05-13T16:11:52+00:00",
        "dateFirstAnswer": "2024-05-13T15:06:50+00:00",
        "dateOperatorAnswer": "2024-05-13T15:06:41+00:00",
        "status": "closed",
        "closeReason": "operator",
        "vote": "none",
        "voteHead": null,
        "commentHead": null,
        "crmEntityType": "deal",
        "crmEntityId": 5317,
        "queueTransfers": 0,
        "waitAnswer": 58,
        "waitClose": 144,
        "kpiFirstAnswer": true,
        "messageCount": 2
      }
    ],
    "hasNextPage": false
  }
}
```

## Error response example

`422` — the period exceeds 1 year:

```json
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "The requested period exceeds the maximum of 1 year", "b24Code": "PERIOD_TOO_LARGE" }
}
```

The `error.message` text is localized. To handle the error, check `error.b24Code`.

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_JSON_BODY` | The request body could not be parsed as JSON. JSON is parsed before fields are checked, so the response says nothing about missing parameters |
| 400 | `INVALID_PARAMS` | The request body is not an object |
| 422 | `BITRIX_ERROR` (`error.b24Code: PERIOD_TOO_LARGE`) | The creation or closing period exceeds 1 year |
| 422 | `BITRIX_ERROR` (`error.b24Code: OFFSET_TOO_LARGE`) | `offset` exceeds the maximum — narrow the period or the filters |
| 422 | `BITRIX_ERROR` (`error.b24Code: INVALID_FILTER`) | Invalid filter value, `status` and `closeReason` passed together, or `kpiFirstAnswer` without a bounded period |
| 422 | `METHOD_NOT_YET_AVAILABLE` | The `imopenlines 26.700.0` update has not reached the Bitrix24 account yet. The response contains an `error.release` field set to `imopenlines 26.700.0` |
| 403 | `B24_TARIFF_RESTRICTION` | The plan does not include Open Channel statistics (`report_open_lines`) |
| 403 | `SCOPE_DENIED` | The key has no `imopenlines` scope |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |

Full list of common API errors: [Errors](/docs/errors).

## See also

- [Per-session metrics](/docs/openlines/sessions/stats)
- [Reassignment history](/docs/openlines/sessions/transfers)
- [Open a client chat](/docs/openlines/sessions/open)
- [Start a session](/docs/openlines/sessions/start)
- [Open Channel sessions](/docs/openlines/sessions)
- [Open Channels](/docs/openlines)