Listings APIListings API
登入
GET/api/v4/listings/scans

列出 listings scans

傳回帳戶的 listings scans，依最新至最舊排序，不含各目錄的結果，並提供分頁資訊與每月配額。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

查詢

名稱類型必填說明預設值
pageinteger選填Page number, starting at 1.1
perPageinteger選填Scans per page, from 1 to 50. Values outside that range are brought back to it.20

回應

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。在批次建立之前讀取此資訊，以確認您還能建立多少次新掃描。當帳戶沒有額度時，其值為 null，例如方案不包含 listings scans 時。

分頁

page 從 1 開始，perPage 預設為 20。pageInfo 會透過 totalRecords、totalPages、hasNextPage 和 hasPreviousPage 告知您目前的分頁位置。請依序請求各頁，並在 hasNextPage 為 false 時停止。

注意事項。

  • 掃描會保留 90 天。超過此期限的掃描不會傳回。
  • 當帳戶尚無掃描時，scans 陣列為空。
  • 讀取清單會計入您的速率限制，占用 1 次請求。請勿藉由讀取清單來等待掃描完成：請直接讀取該掃描，或使用 listing_scan.completed webhook。
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground