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 Administration → 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:

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:

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

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 in your deployment:

ALLOW_UNSAFE_QUERY_AND_FIELDS_API_PARAMS=true

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 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.

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 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:

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

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:
```
fields={"_id":0,"value":0}
```