# Get records

Returns a page of records using `filters`, keyword, time range, and pagination. Supports `json`, `json-ld`, and `markdown`.

This page covers list-specific query and paging semantics. Each element of `data.list[]` has the same shape as `data.data` from [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) for the same `format`.

## Request example



```python [Python + requests]
import requests

url = 'https://open.cli.im/api/v2/rpc/record/getRecords'
data = {
    'filters': {
        'record_template': {'id': 122507},
        'qrcode': {'id': 6762875}
    },
    'format': 'json',
    'search_key': '张三',
    'record_type': 0,
    'page_size': 10,
    'get_total_count': 1
}
headers = {
    'Authorization': 'Bearer <your API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)
```

```bash [curl]
curl -X POST 'https://open.cli.im/api/v2/rpc/record/getRecords' \
  -H 'Authorization: Bearer <your API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"filters": {"record_template": {"id": 122507}, "qrcode": {"id": 6762875}}, "format": "json", "page_size": 10}'
```



## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string | No | Output format, default `json`. Values: `json`, `json-ld`, `markdown` |
| `search_key` | string | No | Fuzzy full-text search across field contents |
| `filters` | object | No | Filter object; see “`filters` fields” below |
| `record_type` | integer | No | Record type: `0` all, `3` state change, `7` subcode edit. Default `0` |
| `start_time` | string \| integer | No | Start time: Unix timestamp or ISO 8601 string |
| `end_time` | string \| integer | No | End time: Unix timestamp or ISO 8601 string |
| `page_size` | integer | No | Page size, max 50, default 10 |
| `page_token` | string | No | Cursor from the previous response |
| `last_record_id` | integer | No | Offset: fetch records after this ID |
| `order_by` | string | No | `{field},{direction}`. Supports `submit_at,desc` and `submit_at,asc`; default `submit_at,desc` |
| `get_total_count` | integer | No | `1` return total count, `0` skip total for speed. Default `1` |

### `filters` fields

`filters` is optional; sub-fields can be combined.

Default scope:

- Omitting `filters` queries within what the API key can see, usually the current org.
- Without `filters.qrcode.id`, results are not restricted by QR code; with only `filters.record_template.id`, you get records for that form.
- Without `filters.record_template.id`, results are not restricted by form; with only `filters.qrcode.id`, you get records for that QR code.
- With both `filters.qrcode.id` and `filters.record_template.id`, you get records for that QR code **and** that form.
- Other `filters.*` combine with AND semantics.

#### `filters.record_template`

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | Form template ID |

#### `filters.qrcode`

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | QR code ID (single) |
| `template_id` | integer | Template ID (batch template codes) |
| `category_id` | integer | QR code category ID (single) |

#### `filters.project`

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | Project (partition) ID |

#### `filters.audit`

| Field | Type | Description |
| --- | --- | --- |
| `stage_id` | integer | Audit stage ID |
| `status` | integer | Audit status: `0` pending / `1` approved / `2` rejected; omit for all |

#### `filters.process_status`

| Field | Type | Description |
| --- | --- | --- |
| `text` | string | Process status text, exact match; see form `process_status_config` |

#### `filters.state_changes`

| Field | Type | Description |
| --- | --- | --- |
| `state_id` | integer | State group ID—records that triggered this state change |

#### `filters.recorder`

| Field | Type | Description |
| --- | --- | --- |
| `auth_id` | integer | Submitter `auth_id` (CaoLiao user auth ID) |

## Output format overview

| Request `format` | `data.list[]` type | Item content | Typical use |
| --- | --- | --- | --- |
| `json` | object | Same as `data.data` for `format=json` in [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) | Parsing, sync, field-level work |
| `json-ld` | object | Same as `format=json-ld` `data.data` there | Semantic exchange, graphs |
| `markdown` | string | Same as `format=markdown` `data.data` there | Reading, export, LLM ingestion |

## Full response skeleton

The blocks below show success skeletons for three formats.



```json [format=json]
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "record_id": 1039879,
        "record_number": "L10610",
        "record_code": "ru6gdTee",
        "record_url": "https://qr46.cn/o4dilp/q0og7BW",
        "submit_at": 1763102668,
        "submit_at_iso": "2025-11-14 14:44:28(UTC+08:00)",
        "submit_method": "微信其他入口填写",
        "recorder": { "auth_id": 16559, "user_id": 831988, "name": "黄**" },
        "project": { "id": 329, "name": "演示会内容", "number": "F2" },
        "qrcode": { "id": 4698286, "name": "灭火器巡检", "type": 0, "type_text": "普通二维码" },
        "org": { "id": 94884306, "name": "南京噗噗网络科技有限公司765", "code": "o4dilp" },
        "record_template": { "id": 25732, "name": "灭火器巡检", "type": 0, "type_text": "普通表单", "number": "D510" },
        "audit": { "enabled": false, "current_stage_id": null, "status": null, "status_text": null },
        "process_status": { "enabled": false, "text": null, "color": null },
        "state_changes": [],
        "tpl_groups": [
          {
            "group_id": 27178,
            "group_title": "",
            "show_group_title": false,
            "is_page_break_group": false,
            "fields": [
              { "field_id": 153984, "field_title": "AI智能填表图片", "field_type": "image", "field_value": [{ "url": "https://ncstatic.clewm.net/rsrc/example.jpg" }] }
            ]
          }
        ]
      }
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}
```

```json [format=json-ld]
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "@context": "https://schema.org",
        "@type": "CreativeWork",
        "identifier": "ru6gdTee",
        "name": "灭火器巡检-L10610",
        "url": "https://qr46.cn/o4dilp/q0og7BW",
        "mainEntity": { "@type": "ItemList", "name": "组件数据" }
      }
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}
```

```json [format=markdown]
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      "---\\ntitle: 灭火器巡检-L10610\\nrecord_id: 1039879\\n...\\n---\\n\\n# 灭火器巡检-L10610\\n\\n## 基本信息\\n\\n**记录编号：** L10610"
    ],
    "next_page_token": "CAESKAoVChMKD3JlY29yZF9hZGRfdGltZRAB...",
    "total": 36
  }
}
```



## Response overview

| Path | Type | Description |
| --- | --- | --- |
| `code` | integer | Platform code; `0` success |
| `message` | string | Message |
| `data` | object | Wrapper |
| `data.list` | array | Records; element type depends on `format` |
| `data.next_page_token` | string | Next page cursor; often `""` when none |
| `data.total` | integer | Total matches; accurate when `get_total_count=1` |

## List items and `getRecord`

`getRecords` does not define a separate record schema. For a given `format`, each `data.list[]` element is identical to `data.data` from [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md).

For field definitions, `tpl_groups` structure, and `field_type`/`field_value` mapping, see [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md) and [Field types overview](https://cli.im/open-api/en/openapi/v2/api/record/components-field-types.md). Per-format schemas (reused from `getRecord`):

**content-json.schema.json (json payload schema)**
<<< ./record-get-record/schema/content-json.schema.json


**content-jsonld.schema.json (json-ld payload schema)**
<<< ./record-get-record/schema/content-jsonld.schema.json


**content-markdown.schema.json (markdown payload schema)**
<<< ./record-get-record/schema/content-markdown.schema.json


> For `format=json`, each list item is already a full record object—batch reads usually do **not** need per-row `getRecord` calls. `getRecord` is better suited when you already have a single `record_id` / `record_url`.

## Suggested filters

| Goal | Suggested parameters |
| --- | --- |
| All records under one QR code | `filters.qrcode.id` |
| Records for one QR + one form | `filters.qrcode.id` + `filters.record_template.id` |
| All records for a form in visible scope | `filters.record_template.id` |
| Global search in visible scope | Omit both QR and form filters; add `search_key`, time, etc. as needed |

## Empty list example

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [],
    "next_page_token": "",
    "total": 0
  }
}
```

## Other conventions

### Pagination

| Case | Description |
| --- | --- |
| First request | `page_token` may be omitted |
| Next page | Pass prior `data.next_page_token` as `page_token` |
| No next page | `next_page_token` is usually `""` |
| Stop condition | Prefer checking whether `next_page_token` is empty |
| `get_total_count=0` | Server may skip total; do not rely on `total` to stop paging |

### Nulls and masking

Same rules as [Get a single record](https://cli.im/open-api/en/openapi/v2/api/record/record-get-record.md). Linked example files are sanitized.

## Error response

```json
{
  "code": 400,
  "error_code": 100300,
  "message": "System error",
  "message_detail": ""
}
```

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | HTTP or platform status |
| `error_code` | integer | Business error code |
| `message` | string | Summary |
| `message_detail` | string | Detail; may be empty |

Full error codes: [Error codes and rate limits](https://cli.im/open-api/en/openapi/v2/error-codes.md).
