列出 listings scans

名称	类型	必填	描述	默认值
page	integer	可选	Page number, starting at 1.	1
perPage	integer	可选	Scans per page, from 1 to 50. Values outside that range are brought back to it.	20

名称

类型

必填

描述

默认值

page

integer

可选

Page number, starting at 1.

perPage

integer

可选

Scans per page, from 1 to 50. Values outside that range are brought back to it.

响应

200A page of scans, newest first. List items carry no `results`; read a scan with GET /listings/scans/{scanId} for those. `quota` is the monthly allowance.

Response

{  "data": {    "listingScans": {      "scans": [        {          "id": "TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz",          "status": "COMPLETED",          "source": "DIRECTORY_SEARCH",          "locationId": null,          "resultsAsOf": "2026-11-05T07:01:51Z",          "createdAt": "2026-11-05T07:01:08Z",          "startedAt": "2026-11-05T07:01:11Z",          "completedAt": "2026-11-05T07:01:51Z",          "business": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "stateIso": "NY",            "postalCode": "10014",            "countryIso": "US",            "phone": "+12123661182"          },          "summary": {            "total": 62,            "found": 21,            "accurate": 18,            "inaccurate": 2,            "notFound": 41,            "pending": 0,            "unavailable": 0          },          "failure": null        },        {          "id": "TGlzdGluZ1NjYW46YWVhNjljOWQtMWJkMC00ODcxLWI1MjctOGMyOWYxNWM2ZDU4",          "status": "COMPLETED",          "source": "DIRECTORY_SEARCH",          "locationId": null,          "resultsAsOf": "2026-11-05T07:01:51Z",          "createdAt": "2026-11-05T07:01:02Z",          "startedAt": "2026-11-05T07:01:11Z",          "completedAt": "2026-11-05T07:01:51Z",          "business": {            "name": "Hattie B's Hot Chicken",            "street": "112 19th Ave S",            "city": "Nashville",            "stateIso": "TN",            "postalCode": "37203",            "countryIso": "US",            "phone": "+16158025700"          },          "summary": {            "total": 62,            "found": 34,            "accurate": 31,            "inaccurate": 2,            "notFound": 28,            "pending": 0,            "unavailable": 0          },          "failure": null        }      ],      "pageInfo": {        "totalPages": 3,        "totalRecords": 6,        "hasNextPage": true,        "hasPreviousPage": false      },      "quota": {        "limit": 50,        "used": 5,        "remaining": 45,        "resetsAt": "2026-11-23T12:38:03Z"      }    }  }}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

列出您的账户已创建的扫描，按从新到旧的顺序排列。每一项的字段与 GET /listings/scans/{scanId} 相同，但不包含 results。每一项中的 summary 包含各项计数；将其 id 传给 GET /listings/scans/{scanId}，即可读取完整结果。

使用场景：查看审查历史。 显示您的团队已运行的扫描，每项扫描均包含对应的商家、状态和 summary。将每一行链接到您基于 GET /listings/scans/{scanId} 构建的扫描页面。

使用场景：创建前检查额度。 quota 提供您套餐的每月额度信息：limit、used、remaining，以及表示下次额度重置时间的 resetsAt。在批量创建之前读取此信息，了解您还可以创建多少次新扫描。当账户没有额度时，例如使用不包含 listings scans 的套餐时，该值为 null。

分页

page 从 1 开始，perPage 默认为 20。pageInfo 通过 totalRecords、totalPages、hasNextPage 和 hasPreviousPage 告知您当前的分页位置。按顺序请求各页，并在 hasNextPage 为 false 时停止。

注意事项。

扫描保留 90 天。超过此期限的扫描不会返回。
当账户尚无扫描时，scans 数组为空。
读取列表会占用您的速率限制中的 1 次请求额度。请勿通过读取列表来等待扫描完成：请直接读取该扫描，或使用 listing_scan.completed webhook。

参数

查询

响应

分页