---
updatedAt: 2026-10-18T18:31:27.000Z
agentTools:
  projectIndex: https://developer.liveswitch.com/llms.txt
---

# List, filter, and sort

Use page, pageSize, where, and order on the list endpoints.

Most list endpoints (`GET /v1/conversations`, `GET /v1/projects`, `GET /v1/contacts`, `GET /v1/tags`, `GET /v1/webhooks`, and more) take the same four query parameters:

| Parameter  | What it does                                       | Default      |
| ---------- | -------------------------------------------------- | ------------ |
| `page`     | The page number, from 1.                           | `1`          |
| `pageSize` | The number of records on each page, from 1 to 100. | `10`         |
| `where`    | A filter, as JSON.                                 | No filter    |
| `order`    | The sort order, as JSON.                           | Newest first |

## Pages

To get all records, increase `page` by 1 until a page has fewer records than `pageSize`.

```
GET /v1/conversations?page=2&pageSize=100
```

`GET /v1/spark-templates` is different: it uses `limit` and `cursor`. Send the `nextCursor` from each response as `cursor` in the next request. The last page has `nextCursor: null`.

## Filter with `where`

`where` is a JSON object. Each key is a field name from the API response. Each value is an operator and a value:

```json
{ "status": { "$eq": "ReadyForReview" } }
```

If you put more than one field in the object, a record must match all of them:

```json
{
  "status": { "$eq": "ReadyForReview" },
  "createdAt": { "$gte": "2026-10-01" }
}
```

| Operator      | Matches                                               | Example                                                |
| ------------- | ----------------------------------------------------- | ------------------------------------------------------ |
| `$eq`         | Equal to                                              | `{ "status": { "$eq": "Completed" } }`                 |
| `$ne`         | Not equal to                                          | `{ "status": { "$ne": "Completed" } }`                 |
| `$gt`, `$gte` | Greater than, greater than or equal to                | `{ "createdAt": { "$gte": "2026-10-01" } }`            |
| `$lt`, `$lte` | Less than, less than or equal to                      | `{ "createdAt": { "$lt": "2026-01-01" } }`             |
| `$in`         | One of the values in a list                           | `{ "status": { "$in": ["InProgress", "Completed"] } }` |
| `$like`       | A text pattern, case-sensitive. `%` matches any text. | `{ "name": { "$like": "Smith%" } }`                    |
| `$ilike`      | A text pattern, not case-sensitive                    | `{ "name": { "$ilike": "%kitchen%" } }`                |
| `$is`         | `null`                                                | `{ "projectId": { "$is": null } }`                     |
| `$not`        | Not equal to one value                                | `{ "status": { "$not": "Completed" } }`                |

`$not` takes one value. It does not take another operator, so `{ "$not": { "$in": [...] } }` returns `400`.

## Sort with `order`

`order` is a JSON list of `[field, direction]` pairs. The direction is `ASC` or `DESC`.

```json
[["status", "ASC"], ["createdAt", "DESC"]]
```

## Example

This JavaScript example gets the newest 25 Conversations that are ready for review:

```javascript
const where = JSON.stringify({ status: { $eq: "ReadyForReview" } });
const order = JSON.stringify([["createdAt", "DESC"]]);

const url = new URL("https://public-api.production.liveswitch.com/v1/conversations");
url.searchParams.set("page", "1");
url.searchParams.set("pageSize", "25");
url.searchParams.set("where", where);
url.searchParams.set("order", order);

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const conversations = await response.json();
```

`URLSearchParams` encodes the JSON for you. If you build the URL yourself, encode `where` and `order` with `encodeURIComponent`.

## Errors

| Error                                                      | Cause                                       |
| ---------------------------------------------------------- | ------------------------------------------- |
| `400` `Invalid where clause — "where" must be valid JSON.` | `where` is not valid JSON.                  |
| `400` `Invalid where column "…".`                          | The field name does not exist.              |
| `400` `Invalid sort column "…".`                           | The field in `order` does not exist.        |
| `400` `The field PageSize must be between 1 and 100.`      | `pageSize` is less than 1 or more than 100. |

# Sibling pages

* [Creating a Conversation](https://developer.liveswitch.com/docs/creating-a-conversation.md)
* [Working with Projects](https://developer.liveswitch.com/docs/working-with-projects.md)
* [Viewing Recordings, Photos, and Sessions (aka Conversations)](https://developer.liveswitch.com/docs/viewing-recordings-photos-and-sessions-aka-conversations.md)
* [Embedding media in a CRM](https://developer.liveswitch.com/docs/embedding-media-in-a-crm.md)
* [Webhooks](https://developer.liveswitch.com/docs/webhooks-1.md)
* [Sparky AI Reports — Integration Guide](https://developer.liveswitch.com/docs/sparky-ai-reports-sparks-integration-guide.md)