---
title: "Query Parameters"
slug: "query-parameters"
updated: 2026-01-08T11:14:02Z
published: 2026-01-08T11:14:02Z
canonical: "developer.rocket.chat/query-parameters"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Parameters

Starting from version `0.49`, specific Rocket.Chat API endpoints support the following query parameters:

- Pagination
- Query and fields

## Pagination

Pagination parameters allow you to control the number of results returned by an API request. The available parameters are listed below:

| Parameter | Example | Description | Format |
| --- | --- | --- | --- |
| `offset` | `50` | The number of items to "skip" in the query. For example, a request returns `count` items after skipping the first `offset` items. | Positive integer |
| `count` | `50` | The number of items to return. | Integer |
| `sort` | `{"value": -1, "_id": 1}` | Defines the fields and direction for sorting results. Use `1` for ascending and `-1` for descending order. | JSON object (key-value pairs for field and order) |

### Pagination parameter settings

To modify the behavior of the `offset` and `count` parameters, go to **Manage** ![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/Screenshot%202025-12-23%20130522.png) **→ Workspace → Settings → General → REST API**.

The following configuration options are available:

- **Default Count**: The default number of results returned by REST API endpoints when the `count` parameter is not specified.
- **Max Record Amount**: The maximum limit for the `count` parameter. If a higher value is provided, this limit will apply instead.
- **Allow Getting Everything**: Enables the API to return all records when the `count` parameter is set to `0`.

These settings give you fine-grained control over how data is paginated, sorted, and returned from Rocket.Chat API responses.

### Example call

- To retrieve a specific page of results with **five items per page**, use the `count=5` and `offset=10` query parameters in your API request:

```powershell
GET http://localhost:3000/api/v1/channels.list?count=5&offset=10
```

- To **sort results** by `name` in descending order and `status` in ascending order, use the `sort` parameter with a JSON object specifying field directions:

```powershell
GET http://localhost:3000/api/v1/users.list?sort={"name":-1,"status":1}
```

## Query and fields

![](https://cdn.us.document360.io/27ca1fd4-36d7-4cde-b4eb-97fc1652954c/Images/Documentation/Deprecated.svg)

The `query` and `fields` parameters have been **deprecated since version 5.0.0** across all supported endpoints to prevent malicious queries. They are **disabled by default starting from version 7.0.0** and can only be re-enabled by setting the following [environment variable](https://docs.rocket.chat/docs/deployment-environment-variables) in your deployment:

```bash
ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS=true
```

> [!CAUTION]
> Security note:
> 
> Enabling these parameters may expose your workspace to security risks. Rocket.Chat is **not responsible** for any vulnerabilities that result from their use. Enable only if absolutely necessary and ensure proper security measures are in place.

When enabled, API responses include a deprecation warning in the response header:`X-Deprecation-Message`. These parameters are **scheduled for removal in version 8.0.0**, after which enabling them will no longer be possible.

### Parameter overview

The `query` and `fields` parameters accept **JSON objects**. The request will fail if an invalid JSON object is provided.

| Parameter | Example | Description |
| --- | --- | --- |
| `query` | To query users with a name that contains the letter "g": `https://localhost:3000/api/v1/users.list?query={ "name": { "$regex": "g" } }` | Allows use of [MongoDB](https://www.mongodb.com/docs/manual/reference/operator/query/) query operators to search for specific data. |
| `fields` | To only retrieve the usernames of users: `http://localhost:3000/api/v1/users.list?fields={ "username": 1 }` | Accepts a JSON object with properties set to `1` or `0` to include or exclude them from the response. |

### Usage notes

- The `query` parameter follows the **EJSON** structure (Extended JSON), similar to standard JSON but with differences in how date and binary fields are handled.
- When querying date fields, you can use either of the following formats:

```bash
query={"_updatedAt":{"$gt":{"$date":1542814057}}}
```

```bash
query={"_updatedAt":{"$gt":{"$date":"2018-11-21T15:27:28.202Z"}}}
```
- To exclude specific fields from the response, you can pass a field value of `0`. For example, to exclude `_id` and `value` fields:

```bash
fields={"_id":0,"value":0}
```

These parameters offer flexible data retrieval capabilities in the Rocket.Chat REST API but should only be used in **controlled or development environments** due to potential security implications.