Query Parameters
    • Dark
    • PDF

    Query Parameters

    • Dark
    • PDF

    Article summary

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

    • Pagination

    • Query and fields


    The pagination query parameters are as follows:







    The number of items to "skip" in the query, i.e. requests return count items, skipping the first offset items.

    Positive integer



    The number of items to return.



    {"value": -1, "_id": 1}

    List of fields to order by, and in which direction.

    JSON object, with properties listed in the desired order, with values of 1 for ascending or -1 for descending.

    Pagination parameter settings

    To modify the offset and count behavior, you can access the REST API settings in Administration > Workspace > Settings > General > REST API.

    • Default Count: The default count for REST API results if the count parameter is not provided.

    • Max Record Amount: The maximum limit for the count parameter. If a higher count is specified, this limit will be applied.

    • Allow Getting Everything: This setting determines whether passing 0 as the count parameter is allowed to retrieve all records.

    This feature provides flexibility in controlling the number of results, pagination, and sorting in the Rocket.Chat API.

    Example call

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

    • To sort the results by name in descending order and status in ascending order, use the sort parameter with the appropriate JSON syntax:


    Query and fields

    The query and fields parameters are deprecated since 5.0.0 and are planned to be removed in the 7.0.0 release.

    The query and fields parameters accept JSON objects, but the request will fail if an invalid JSON object is provided.





    To query users with a name that contains the letter "g":

    https://localhost:3000/api/v1/users.list?query={ "name": { "$regex": "g" } }

    This parameter allows you to use MongoDB query operators to search for specific data.


    To only retrieve the usernames of users:

    http://localhost:3000/api/v1/users.list?fields={ "username": 1 }

    This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response.

    Note that the query parameter follows the EJSON structure, similar to JSON, but with some differences in handling date and binary fields. For queries involving date fields, you can use the following examples:

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

    If you provide a field value of {"_id": false, "value": false}, you can retrieve all other fields except for _id and value.

    These query and field parameters enhance the flexibility and precision of data retrieval in the Rocket.Chat API.

    Was this article helpful?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.