# Query Record List
Get the record list that meets specified conditions
## Request
Facts |
---|---
HTTP URL | https://open.feishu.cn/open-apis/apaas/v1/applications/:namespace/objects/:object_api_name/records/batch_query
HTTP Method | POST
Rate Limit | [1000 per minute & 50 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes
**To use this API, you must have at least 1 of the listed scopes.** | View object record(app_engine:object.record:read)
### Request header
Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`
**Value format**: "Bearer `access_token`"
**Example value**: "Bearer t-7f1bcd13fc57d46bac21793a18e560"
[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"
### Path parameters
Parameter | Type | Description
---|---|---
namespace | string | **Example value**: "package_test__c"
**Data validation rules**:
- Length range: `0` ～ `256` characters
object_api_name | string | **Example value**: "_user"
**Data validation rules**:
- Length range: `0` ～ `256` characters
### Request body
Parameter | Type | Required | Description
---|---|---|---
select | string\[\] | Yes | Field to get. Using the unique identifier of field to query. Joined fields can be drilled down by "."
**Example value**: ["_name"]
**Data validation rules**:
- Length range: `0` ～ `256`
filter | criterion | No | Filter condition. Conditions are specified in the JSON format
conditions | condition\[\] | No | Conditions array
**Data validation rules**:
- Length range: `0` ～ `10`
index | string | No | The index of the current condition. Used in logic
**Example value**: "1"
left | condition_value | No | Left value of filter condition
type | string | No | Type: The left value contains the following options: 1. metadataVariable
**Example value**: "metadataVariable"
settings | string | No | Configuration of left or right value in JSON format
**Example value**: "{\"fieldPath\":[{\"fieldApiName\": \"_id\",\"objectApiName\": \"_user\"}]}"
right | condition_value | No | Right value of filter condition
type | string | No | Type: The right value contains the following options: 1. constant
**Example value**: "constant"
settings | string | No | Configuration of left or right value in JSON format
**Example value**: "{\"data\":\"123456\"}"
operator | string | No | Operator for linking left and right values
**Example value**: "equal"
logic_expression | string | No | The logical relationship between multiple conditions
**Example value**: "1 and 2"
order_by | sort\[\] | No | Sorting parameters. Conditions are specified in the JSON format. Specifically, "field" refers to the fields to be sorted and "direction" refers to the sorting order in which multiple conditions take effect according to their order in the array.
**Data validation rules**:
- Length range: `0` ～ `256`
field | string | Yes | API Name of the field
**Example value**: "_id"
**Data validation rules**:
- Length range: `0` ～ `256` characters
direction | string | Yes | Sorting parameter: sort direction
**Example value**: "ASC"
**Optional values are**:
- ASC：ascending order
- DESC：descending order
**Data validation rules**:
- Length range: `0` ～ `256` characters
group_by | record_group_by_item\[\] | No | Aggregate parameter. Conditions are specified in JSON format. Specifically, "field" refers to the fields that will be aggregated.
**Data validation rules**:
- Length range: `0` ～ `256`
field | string | Yes | API Name of the field
**Example value**: "_id"
**Data validation rules**:
- Length range: `0` ～ `256` characters
page_token | string | No | Page identifier. It is not filled in the first request, indicating traversal from the beginning; when there will be more groups, the new page_token will be returned at the same time, and the next traversal can use the page_token to get more groups
**Example value**: "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0="
use_page_token | boolean | No | Whether to use page_token. If true, the value of page_token is used as the start position to query records, and next_page_token will be returned in response. False by default.
**Example value**: false
page_size | int | No | The number of records to be returned by the server side, maximum 500 entries. The value will be 500 by default if left blank.
**Example value**: 100
offset | int | No | Return the offset of the record, which is 0 by default, that is, return from the first record found. The query performance will be poor if the offset is large, and it may result in API response timeout. It's recommended to use ID cursor-based pagination when pulling all records
**Example value**: 0
**Data validation rules**:
- Value range: `0` ～ `10000000000`
need_total_count | boolean | No | Whether to return the total number of conditions that meet the conditions (Total). False by default, the total number will not be returned.
**Example value**: true
### Request body example
```json
{
"select": [
"_name"
],
"filter": {
"conditions": [
{
"index": "1",
"left": {
"type": "metadataVariable",
"settings": "{\"fieldPath\":[{\"fieldApiName\": \"_id\",\"objectApiName\": \"_user\"}]}"
},
"right": {
"type": "constant",
"settings": "{\"data\":\"123456\"}"
},
"operator": "equal"
}
],
"logic_expression": "1 and 2"
},
"order_by": [
{
"field": "_id",
"direction": "ASC"
}
],
"group_by": [
{
"field": "_id"
}
],
"page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
"use_page_token": false,
"page_size": 100,
"offset": 0,
"need_total_count": true
}
```
## Response
### Response body
Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
items | string | List of records that meet the conditions
total | int | Number of records that meet the conditions
next_page_token | string | Token for where the next page starts from, which will not be returned when reaching the end of the page
has_more | boolean | Whether the response body has more parameters
### Response body example
```json
{
"code": 0,
"msg": "success",
"data": {
"items": "[{}]",
"total": 0,
"next_page_token": "null",
"has_more": true
}
}
```
### Error code
HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 2320001 | param is invalid | Please check the input parameters