List listings scans

Name	Type	Required	Description	Default
page	integer	optional	Page number, starting at 1.	1
perPage	integer	optional	Scans per page, from 1 to 50. Values outside that range are brought back to it.	20

Name

Type

Required

Description

Default

page

integer

optional

Page number, starting at 1.

perPage

integer

optional

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

Responses

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.

Lists the scans your account has created, newest first. Each item has the same fields as GET /listings/scans/{scanId} except that results is not included. The summary on each item has the counts; pass its id to GET /listings/scans/{scanId} to read the full results.

Use case: a history of audits. Show the scans your team has run, each with its business, status and summary. Link each row to the scan page you build on GET /listings/scans/{scanId}.

Use case: checking the allowance before you create. quota reports the monthly allowance for your plan: limit, used, remaining, and resetsAt, when the allowance next resets. Read it before a batch of creates to see how many fresh scans you have left. It is null when the account has no allowance, for example on a plan that does not include listings scans.

Paging

page starts at 1 and perPage defaults to 20. pageInfo tells you where you are: totalRecords, totalPages, hasNextPage and hasPreviousPage. Request the pages in order and stop when hasNextPage is false.

Notes.

Scans are kept for 90 days. Older scans are not returned.
The scans array is empty when the account has no scans yet.
Reading the list costs one request against your rate limit. Do not use it to wait for a scan: read that scan directly, or use the listing_scan.completed webhook.

Parameters

Query

Responses

Paging