获取记录列表

按 filters、关键字、时间和分页条件获取记录列表，支持 json、json-ld、markdown 三种输出格式。

本文档聚焦列表接口自己的查询与分页语义；data.list[] 中每一条记录的内容结构，与 获取单条记录 在相同 format 下的 data.data 保持一致。

请求示例

Python + requestscurl

python

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 <你的API Key>',
    'Content-Type': 'application/json'
}
response = requests.post(url, json=data, headers=headers)
print(response.text)

bash

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

请求参数

参数	类型	必填	说明
`format`	string	否	输出格式，默认 `json`。可选值：`json`、`json-ld`、`markdown`
`search_key`	string	否	组件内容关键字模糊查询，对记录内字段全文检索
`filters`	object	否	筛选条件对象，可组合使用；详见下方「`filters` 子字段说明」
`record_type`	integer	否	记录类型筛选：`0` 全部，`3` 状态变更，`7` 子码编辑。默认 `0`
`start_time`	string \| integer	否	开始时间，支持 Unix 时间戳或 ISO 8601 字符串
`end_time`	string \| integer	否	结束时间，支持 Unix 时间戳或 ISO 8601 字符串
`page_size`	integer	否	每页记录数，最大 50，默认 10
`page_token`	string	否	分页游标，由上一页响应返回
`last_record_id`	integer	否	记录 ID 偏移，从此 ID 之后开始查
`order_by`	string	否	排序方式，格式为 `{字段},{方向}`。支持 `submit_at,desc`（按提交时间降序）和 `submit_at,asc`（按提交时间升序）；默认 `submit_at,desc`
`get_total_count`	integer	否	是否返回总数：`1` 返回，`0` 可跳过总数统计以提升性能。默认 `1`

`filters` 子字段说明

filters 为可选对象，可包含以下子字段，支持组合使用。

缺省范围说明：

filters 整体可省略；省略时，表示在当前 API Key 可见范围内查询记录，通常为当前企业范围内的记录。
未传 filters.qrcode.id 时，表示不按二维码限制；如果仅传 filters.record_template.id，则表示查询该表单下的记录。
未传 filters.record_template.id 时，表示不按表单限制；如果仅传 filters.qrcode.id，则表示查询该二维码下的记录。
同时传 filters.qrcode.id + filters.record_template.id 时，表示查询“该二维码下、该表单产生的记录”，适合精确定位某个码上的某个表单记录。
其他 filters.* 子字段与上述条件按组合条件共同生效。

`filters.record_template`

字段	类型	说明
`id`	integer	表单模板 ID

`filters.qrcode`

字段	类型	说明
`id`	integer	二维码 ID，支持单个
`template_id`	integer	二维码模板 ID（批量模板码）
`category_id`	integer	二维码分组 ID，支持单个

`filters.project`

字段	类型	说明
`id`	integer	分区 ID

`filters.audit`

字段	类型	说明
`stage_id`	integer	审核阶段 ID
`status`	integer	审核状态：`0` 待审核 / `1` 审核通过 / `2` 审核不通过；不传表示全部状态

`filters.process_status`

字段	类型	说明
`text`	string	处理状态文本，精确匹配；可选值参考表单详情中的 `process_status_config`

`filters.state_changes`

字段	类型	说明
`state_id`	integer	状态组 ID，筛选触发了该状态变更的记录

`filters.recorder`

字段	类型	说明
`auth_id`	integer	填表人 `auth_id`（草料平台用户授权 ID）

返回格式概览

请求 `format`	`data.list[]` 类型	列表项内容来源	适用场景
`json`	object	与 `获取单条记录` 中 `format=json` 的 `data.data` 一致	程序化解析、数据同步、字段级处理
`json-ld`	object	与 `获取单条记录` 中 `format=json-ld` 的 `data.data` 一致	语义化数据交换、知识图谱、语义检索
`markdown`	string	与 `获取单条记录` 中 `format=markdown` 的 `data.data` 一致	阅读展示、归档导出、交给 LLM 做阅读类处理

配套资源：

format=json 完整成功响应：success-normal.response.json

完整返回示例

以下代码块展示三种 format 的成功响应骨架；完整 JSON 样例请使用上面的配套文件。

format=jsonformat=json-ldformat=markdown

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

{
  "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

{
  "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
  }
}

响应结构总览

路径	类型	说明
`code`	integer	平台状态码，`0` 表示成功
`message`	string	状态消息
`data`	object	业务响应包装层
`data.list`	array	记录列表；元素类型由请求 `format` 决定
`data.next_page_token`	string	下一页分页游标；无下一页时通常返回空字符串
`data.total`	integer	符合条件的记录总数；通常在 `get_total_count=1` 时返回准确统计值

列表项结构说明

与 `getRecord` 的复用关系

getRecords 不再额外定义一套独立的记录内容 schema。相同 format 下，data.list[] 中的每一项与 获取单条记录 的 data.data 结构一致。

format=json：每个元素都是完整的记录详情对象。字段总览、tpl_groups[]、tpl_groups[].fields[]、field_type 与 field_value 的映射规则，请直接参考 获取单条记录、content-json-v1.schema.json 和 components-field-types.md。
format=json-ld：每个元素都是 Schema.org 风格对象，结构与 获取单条记录 中 format=json-ld 的 data.data 一致；可复用 content-jsonld-v1.schema.json。
format=markdown：每个元素都是完整 Markdown 文本，结构与 获取单条记录 中 format=markdown 的 data.data 一致；可复用 content-markdown-v1.schema.json。

如果你在做程序接入或 agent 检索，建议先读取本页的列表层字段，再按 format 跳转到详情接口对应 schema 解析每个列表项。

补充说明：

当 format=json 时，data.list[] 中的每一项已经是完整记录详情对象；如果只是批量读取记录内容，通常不需要再逐条调用 获取单条记录。
获取单条记录 更适合以下场景：你已经拿到了单个 record_id / record_url，或只需要精确读取某一条记录。

目标	推荐参数
查询某个二维码下的全部记录	`filters.qrcode.id`
查询某个二维码下某个表单的记录	`filters.qrcode.id + filters.record_template.id`
查询某个表单在当前可见范围内的全部记录	`filters.record_template.id`
在当前 API Key 可见范围内做全局记录检索	可不传 `filters.qrcode.id` 与 `filters.record_template.id`，再按需叠加 `search_key`、时间范围或其他 `filters.*`

空列表示例

json

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

其他字段约定

分页约定

场景	说明
首次查询	可不传 `page_token`
存在下一页	将上一次响应中的 `data.next_page_token` 原样传回请求参数 `page_token`
无下一页	`data.next_page_token` 通常为空字符串
是否继续翻页	建议始终以 `data.next_page_token` 是否为空作为判断依据
`get_total_count=0`	服务端可跳过总数统计以提升性能；此时不建议依赖 `data.total` 作为翻页终止条件

空值与脱敏约定

列表项中的空值、空数组、空字符串、关联对象为空值以及脱敏规则，与 获取单条记录 完全一致。

文档中链接到的示例文件均已做脱敏处理，仅用于结构说明与联调参考。

错误响应

失败时通常返回非成功状态，响应体可能包含以下字段：

json

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

字段	类型	说明
`code`	integer	HTTP 状态码或平台错误状态
`error_code`	integer	业务错误码
`message`	string	错误摘要
`message_detail`	string	详细错误信息，可能为空字符串

具体错误码定义见：错误码说明。

二维码

活码

表单

批量模板 & 子码

记录

成员

活码

表单与记录

安装教程

企业微信版购买

常见问题

获取记录列表

请求示例

请求参数

`filters` 子字段说明

`filters.record_template`

`filters.qrcode`

`filters.project`

`filters.audit`

`filters.process_status`

`filters.state_changes`

`filters.recorder`

返回格式概览

完整返回示例

响应结构总览

列表项结构说明

与 `getRecord` 的复用关系

推荐过滤策略

空列表示例

其他字段约定

分页约定

空值与脱敏约定

错误响应

获取记录列表 ​

请求示例 ​

请求参数 ​

filters 子字段说明 ​

filters.record_template ​

filters.qrcode ​

filters.project ​

filters.audit ​

filters.process_status ​

filters.state_changes ​

filters.recorder ​

返回格式概览 ​

完整返回示例 ​

响应结构总览 ​

列表项结构说明 ​

与 getRecord 的复用关系 ​

推荐过滤策略 ​

空列表示例 ​

其他字段约定 ​

分页约定 ​

空值与脱敏约定 ​

错误响应 ​

获取记录列表

请求示例

请求参数

`filters` 子字段说明

`filters.record_template`

`filters.qrcode`

`filters.project`

`filters.audit`

`filters.process_status`

`filters.state_changes`

`filters.recorder`

返回格式概览

完整返回示例

响应结构总览

列表项结构说明

与 `getRecord` 的复用关系

推荐过滤策略

空列表示例

其他字段约定

分页约定

空值与脱敏约定

错误响应