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

# List Records

> Search for records of a particular class.

#### Recipes

<AccordionGroup>
  <Accordion title="Filter records by location">
    <Steps>
      <Step title="1. Set a search operator for a field">
        Apply a search operator to the query. Here, the `near` operator is applied to a `user_location` field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "QB-Token: b97d22aee7773587ede6b2120fda1d0d7c012bba" \
        https://api.quickblox.com/data/ScoreTable.json?user_location[near]=11.00,45.40;16800
        ```
      </Step>

      <Step title="2. As a result, the API returns records filtered by the specified location.">
        All records with the `11.00,45.40;16800` value for the `user_location` field are turned.

        ```json theme={null}
        {
          "class_name": "ScoreTable",
          "skip": 0,
          "limit": 100,
          "items": [
            {
              "_id": "5d866b53a28f9a5ad51cb562",
              "_parent_id": null,
              "completed_levels": [
                1,
                2,
                3,
                4
              ],
              "created_at": 1569090387,
              "date": "2019-09-21T21:21:00Z",
              "expert_mode": false,
              "game_mode_name": "beta testing",
              "progress": 0.23,
              "score_value": 1000,
              "updated_at": 1574944158,
              "user_avatar": null,
              "user_id": 96753878,
              "user_location": [
                11.12,
                45.51
              ]
            },
            {
              "_id": "5d866a5aa0eb4753fc6099c3",
              "_parent_id": null,
              "completed_levels": [
                1,
                2,
                3,
                10,
                11,
                12,
                13
              ],
              "created_at": 1569090138,
              "date": "2019-09-21T21:21:00Z",
              "expert_mode": false,
              "game_mode_name": "4x4",
              "progress": 0.12,
              "score_value": 665,
              "updated_at": 1569189981,
              "user_avatar": null,
              "user_id": 96753878,
              "user_location": [
                11.13,
                45.52
              ]
            }
          ]
        }
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Filter records by criteria">
    <Steps>
      <Step title="1. Set a search operator for a field">
        Apply a search operator to the query. Here, the `lt` operator is applied to a `score_value` custom field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "QB-Token: 0bea0abd041b2431e5e1c2d0b06fab4414012bba" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[lt]=1000
        ```
      </Step>

      <Step title="2. As a result, the API returns records filtered upon the request.">
        All records with the `score_value` less than `1000` are returned.

        ```json theme={null}
        {
          "class_name": "ScoreTable",
          "skip": 0,
          "limit": 100,
          "items": [
            {
              "_id": "5d866a5aa0eb4753fc6099c3",
              "_parent_id": null,
              "completed_levels": [
                1,
                2,
                3,
                10,
                11,
                12,
                13
              ],
              "created_at": 1569090138,
              "date": "2019-09-21T21:21:00Z",
              "expert_mode": false,
              "game_mode_name": "beta testing4",
              "progress": 0.12,
              "score_value": 665,
              "updated_at": 1569177165,
              "user_avatar": null,
              "user_id": 96753878,
              "user_location": [
                11.13,
                45.52
              ]
            }
          ]
        }
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Group records">
    <Steps>
      <Step title="1. Set an aggregation operator for a field to calculate an average for all numeric values">
        Apply an aggregation operator for a field to calculate an average for all numeric values.

        Here, the `calc` aggregation operator is applied to the `score_value` and set to the avg value.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "QB-Token: 0bea0abd041b2431e5e1c2d0b06fab4414012bba" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[calc]=avg&group_by=game_mode_name
        ```
      </Step>

      <Step title="2. Set an aggregation operator for a field to group records">
        Apply an aggregation operator to a field to group records. Here, a group\_by operator is applied to a `game_mode_name` field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "QB-Token: 0bea0abd041b2431e5e1c2d0b06fab4414012bba" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[calc]=avg&group_by=game_mode_name
        ```
      </Step>

      <Step title="3. As a result, the API returns records grouped according to the request.">
        The records are grouped by the `gamed_mode_name` field with an average calculated for the `score_value` field.

        ```json theme={null}
        {
          "class_name": "ScoreTable",
          "skip": 0,
          "limit": 100,
          "items": [
            {
              "game_mode_name": "4x4",
              "avg": 665
            },
            {
              "game_mode_name": "beta testing",
              "avg": 2010.5
            },
            {
              "game_mode_name": "team rumble",
              "avg": 1211
            }
          ]
        }
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Filter records by location with API key">
    <Steps>
      <Step title="1. Use 'Authorization' header to pass API key">
        ```curl {3} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?user_location[near]=11.00,45.40;16800
        ```
      </Step>

      <Step title="2. Set a search operator for a field">
        Apply a search operator to the query. Here, the `near` operator is applied to a `user_location` field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?user_location[near]=11.00,45.40;16800
        ```
      </Step>

      <Step title="3. As a result, the API returns records filtered by the specified location.">
        All records with the `11.00,45.40;16800` value for the `user_location` field are turned.

        ```json theme={null}
        {
          "class_name": "ScoreTable",
          "skip": 0,
          "limit": 100,
          "items": [
            {
              "_id": "5d866b53a28f9a5ad51cb562",
              "_parent_id": null,
              "completed_levels": [
                1,
                2,
                3,
                4
              ],
              "created_at": 1569090387,
              "date": "2019-09-21T21:21:00Z",
              "expert_mode": false,
              "game_mode_name": "beta testing",
              "progress": 0.23,
              "score_value": 1000,
              "updated_at": 1574944158,
              "user_avatar": null,
              "user_id": 96753878,
              "user_location": [
                11.12,
                45.51
              ]
            },
            {
              "_id": "5d866a5aa0eb4753fc6099c3",
              "_parent_id": null,
              "completed_levels": [
                1,
                2,
                3,
                10,
                11,
                12,
                13
              ],
              "created_at": 1569090138,
              "date": "2019-09-21T21:21:00Z",
              "expert_mode": false,
              "game_mode_name": "4x4",
              "progress": 0.12,
              "score_value": 665,
              "updated_at": 1569189981,
              "user_avatar": null,
              "user_id": 96753878,
              "user_location": [
                11.13,
                45.52
              ]
            }
          ]
        }
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Filter records by criteria with API key">
    <Steps>
      <Step title="1. Use 'Authorization' header to pass API key">
        ```curl {3} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[lt]=1000
        ```
      </Step>

      <Step title="2. Set a search operator for a field">
        Apply a search operator to the query. Here, the `lt` operator is applied to a `score_value` custom field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[lt]=1000
        ```
      </Step>

      <Step title="3. As a result, the API returns records filtered upon the request.">
        All records with the `score_value` less than `1000` are returned.

        ```json theme={null}
        {
          "class_name": "ScoreTable",
          "skip": 0,
          "limit": 100,
          "items": [
            {
              "_id": "5d866a5aa0eb4753fc6099c3",
              "_parent_id": null,
              "completed_levels": [
                1,
                2,
                3,
                10,
                11,
                12,
                13
              ],
              "created_at": 1569090138,
              "date": "2019-09-21T21:21:00Z",
              "expert_mode": false,
              "game_mode_name": "beta testing4",
              "progress": 0.12,
              "score_value": 665,
              "updated_at": 1569177165,
              "user_avatar": null,
              "user_id": 96753878,
              "user_location": [
                11.13,
                45.52
              ]
            }
          ]
        }
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Group records with API key">
    <Steps>
      <Step title="1. Use 'Authorization' header to pass API key">
        ```curl {3} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[calc]=avg&group_by=game_mode_name
        ```
      </Step>

      <Step title="2. Set an aggregation operator for a field to calculate an average for all numeric values">
        Apply an aggregation operator for a field to calculate an average for all numeric values.

        Here, the `calc` aggregation operator is applied to the `score_value` and set to the avg value.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[calc]=avg&group_by=game_mode_name
        ```
      </Step>

      <Step title="3. Set an aggregation operator for a field to group records">
        Apply an aggregation operator to a field to group records. Here, a group\_by operator is applied to a `game_mode_name` field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Content-Type: application/json" \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        https://api.quickblox.com/data/ScoreTable.json?score_value[calc]=avg&group_by=game_mode_name
        ```
      </Step>

      <Step title="4. As a result, the API returns records grouped according to the request.">
        The records are grouped by the `gamed_mode_name` field with an average calculated for the `score_value` field.

        ```json theme={null}
        {
          "class_name": "ScoreTable",
          "skip": 0,
          "limit": 100,
          "items": [
            {
              "game_mode_name": "4x4",
              "avg": 665
            },
            {
              "game_mode_name": "beta testing",
              "avg": 2010.5
            },
            {
              "game_mode_name": "team rumble",
              "avg": 1211
            }
          ]
        }
        ```
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Info>
  If you are sorting records **by time**, use the `_id` field. It is indexed and will be much faster than the `created_at` field.
</Info>

Combinations of operators are allowed. For example:\
`score_value[gt]=100&score_value[lt]=1000&game_mode_name[in]=deathmatch,ctf`

**Search Operators**

The request can contain all, some or none of the next search operators:

| Operator | Description                                                                                                                                                                                                                                                                                               |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| lt       | **Less Than** operator  <br />  <br />Types: integer, float  <br />  <br />Example:  <br />score\_value\[lt]=1000                                                                                                                                                                                         |
| lte      | **Less Than or Equal to** operator  <br />  <br />Types: integer, float  <br />  <br />Example:  <br />score\_value\[lte]=850                                                                                                                                                                             |
| gt       | **Greater Than** operator  <br />  <br />Types: integer, float  <br />  <br />Example:  <br />bonus\_count\[gt]=2.45                                                                                                                                                                                      |
| gte      | **Greater Than or Equal to** operator  <br />  <br />Types: integer, float  <br />  <br />Example:  <br />bonus\_count\[gte]=56.443                                                                                                                                                                       |
| ne       | **Not Equal to** operator  <br />  <br />Types: integer, float, string, boolean  <br />  <br />Example:  <br />game\_mode\_name\[ne]=ctf                                                                                                                                                                  |
| in       | **Contained IN array** operator  <br />  <br />Types: integer, float, string  <br />  <br />Example:  <br />game\_mode\_name\[in]=deathmatch,rage                                                                                                                                                         |
| nin      | **Not contained IN array** operator  <br />  <br />Types: integer, float, string  <br />  <br />Example:  <br />game\_mode\_name\[nin]=survivor,crazy\_nightmare                                                                                                                                          |
| all      | **ALL contained IN array** operator  <br />  <br />Types: array  <br />  <br />Example:  <br />game\_modes\[all]=survivor,crazy                                                                                                                                                                           |
| or       | **OR** operator  <br />  <br />Types: integer, float, string  <br />  <br />Example:  <br />name\[or]=sam,tim  <br />name\[or]=sam\&lastname\[or]=johnson  <br />  <br />Will return records with name `sam` **or** `tim`.  <br />  <br />Will return records with name `sam` **or** last name `johnson`. |
| ctn      | **Contains** substring operator  <br />  <br />Types: string  <br />  <br />Example:  <br />username\[ctn]=son  <br />  <br />Will return all records where `username` field **contains** `son` substring.                                                                                                |
| near     | Types: location  <br />  <br />Example:  <br />mylocation\[near]=25.32,44.551;1000  <br />  <br />Search records in a specific radius with  <br />the current position in meters.  <br />Format: `{field_name}[near]=longitude,latitude;radius`.                                                          |

**Sort Operators**

Next sorting operators are allowed:

| Operator   | Description                                                                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sort\_asc  | Types: all types  <br />  <br />Example:  <br />sort\_asc=field\_name  <br />  <br />Search results will be sorted by the specified field in ascending order.   |
| sort\_desc | Types: all types  <br />  <br />Example:  <br />sort\_desc=field\_name  <br />  <br />Search results will be sorted by the specified field in descending order. |

**Aggregation Operators**

| Operator                 | Description                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \{field\_name}\[calc]=   | Types: integer,  <br />float  <br />  <br />Example:  <br />rating\[calc]=min  <br />  <br />`avg`, `min`, `max`, `sum` can be used with `group_by` operator.                                                         |
| group\_by=\{field\_name} | Types: integer, float, string, boolean  <br />  <br />Example:  <br />group\_by=game\_mode\_name  <br />  <br />The `group_by` works similarly to the SQL GROUP BY operator, should be used with the `calc` operator. |

#### Path Parameters

<ParamField path="class_name" type="string" required>
  Custom object class name.
</ParamField>

#### Query Parameters

<ParamField query="{custom_field_N}" type="string">
  Search records with the field that contains the specified value. Can be many 1..N.
</ParamField>

<ParamField query="{custom_field_N}[{search_operator}]" type="string">
  Search a record with the field that contains a value according to the specified value and operator.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Limit search results to N records. Max(Cloud/Enterprise): 100/1000. Useful for pagination.
</ParamField>

<ParamField query="skip" type="integer" default="0">
  Skip N records in search results. Useful for pagination.
</ParamField>

<ParamField query="count" type="integer">
  Count search results. Response will contain only count of records found.
</ParamField>

<ParamField query="sort_desc" type="string">
  Search results will be sorted by specified field in descending order.
</ParamField>

<ParamField query="sort_asc" type="string">
  Search results will be sorted by specified field in ascending order.
</ParamField>

<ParamField query="output[include]" type="string">
  The `output` parameter takes the form of a record with a list of fields for inclusion or exclusion
  from the result set. `output[include]` specifies the fields to include. The `_id` field is,
  by default, included in the result set. To exclude the `_id` field from the result set, you need
  to specify the exclusion of the `_id` field in the `output[exclude]` value.
</ParamField>

<ParamField query="output[exclude]" type="string">
  The `output` parameter takes the form of a record with a list of fields for inclusion or exclusion
  from the result set. `output[exclude]` specifies the fields to exclude. The `_id` field is,
  by default, included in the result set. To exclude the `_id` field from the result set, you need
  to specify the exclusion of the `_id` field in the `output[exclude]` value.
</ParamField>

#### Headers

<ParamField header="QB-Token" type="string" required> A user or application session token. See [Authentication](/reference/authentication) page to learn more about session tokens. Must be used either QB-Token or Authorization. </ParamField>

<ParamField header="Authorization" type="string" default="ApiKey {your_api_key}">
  API key from Dashboard. Expected format: `ApiKey {your_api_key}`. Must be used
  either QB-Token or Authorization.
</ParamField>

<ParamField header="On-Behalf-Of" type="string">
  User ID. The user ID of the user on whose behalf the request is being made.
</ParamField>

#### Response

<AccordionGroup>
  <Accordion title="200">
    A successful response

    <ResponseField name="class_name" type="string" />

    <ResponseField name="skip" type="integer" />

    <ResponseField name="limit" type="integer" />

    <ResponseField name="items" type="array of objects" />

    <Expandable title="properties">
      <ResponseField name="_id" type="string" />

      <ResponseField name="_parent_id" type="string" />

      <ResponseField name="created_at" type="integer" />

      <ResponseField name="updated_at" type="integer" />

      <ResponseField name="user_id" type="integer" />
    </Expandable>
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET \
  -H "Content-Type: application/json" \
  -H "QB-Token: 0bea0abd041b2431e5e1c2d0b06fab4414012bba" \
  https://api.quickblox.com/data/ScoreTable.json?score_value[lt]=1000
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "class_name": "ScoreTable",
    "skip": 0,
    "limit": 100,
    "items": [
      {
        "_id": "5d866a5aa0eb4753fc6099c3",
        "_parent_id": null,
        "completed_levels": [
          1,
          2,
          3,
          10,
          11,
          12,
          13
        ],
        "created_at": 1569090138,
        "date": "2019-09-21T21:21:00Z",
        "expert_mode": false,
        "game_mode_name": "beta testing4",
        "progress": 0.12,
        "score_value": 665,
        "updated_at": 1569177165,
        "user_avatar": null,
        "user_id": 96753878,
        "user_location": [
          11.13,
          45.52
        ]
      }
    ]
  }
  ```
</ResponseExample>