GET/api/v4/listings/scans/{scanId}

Get a listings scan

Returns one listings scan with its summary and per-directory results, partial while the scan is still running.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Path

Name	Type	Required	Description
scanId	string	required	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Responses

200A completed scan. The real response lists every directory in `results`, usually around 60. This example is trimmed to six entries, one of each kind described below.

Response

{  "data": {    "listingScan": {      "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,      "results": [        {          "directory": {            "id": 1,            "name": "Google Maps",            "url": "maps.google.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014, USA",            "phones": [              "+1 212-366-1182"            ],            "url": "https://maps.google.com/?cid=4877966330195296067"          },          "syncStatus": null        },        {          "directory": {            "id": 2,            "name": "Yelp",            "url": "yelp.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine St",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014",            "phones": [              "+12123661182"            ],            "url": "https://www.yelp.com/biz/joes-pizza-new-york-4"          },          "syncStatus": null        },        {          "directory": {            "id": 374,            "name": "Map Quest",            "url": "www.mapquest.com"          },          "status": "FOUND",          "accurate": null,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "MISSING",              "message": "Not shown"            },            "phone": {              "status": "MISSING",              "message": "Not shown"            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine St",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": null,            "fullAddress": "7 Carmine St, New York, NY 10014, US",            "phones": [],            "url": null          },          "syncStatus": null        },        {          "directory": {            "id": 352,            "name": "YellowPages",            "url": "www.yellowpages.com"          },          "status": "NOT_FOUND",          "accurate": null,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": null,          "listing": null,          "syncStatus": null        },        {          "directory": {            "id": 50,            "name": "Judys Book",            "url": "judysbook.com"          },          "status": "FOUND",          "accurate": false,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "INACCURATE",              "message": "Phone number does not match"            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 CARMINE ST",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": null,            "fullAddress": "7 CARMINE ST, New York, NY 10014",            "phones": [              "8553685707"            ],            "url": "https://www.judysbook.com/Joes-Pizza-Uncategorized-newyork-r29271293.htm"          },          "syncStatus": null        },        {          "directory": {            "id": 350,            "name": "Uber",            "url": "uber.com"          },          "status": "FOUND",          "accurate": true,          "accuracySource": "DIRECTORY_MATCH",          "accuracy": {            "name": {              "status": "ACCURATE",              "message": null            },            "address": {              "status": "ACCURATE",              "message": null            },            "phone": {              "status": "ACCURATE",              "message": null            }          },          "listing": {            "name": "Joe's Pizza",            "street": "7 Carmine Street",            "city": "New York",            "state": "NY",            "postalCode": "10014",            "country": "US",            "fullAddress": "7 Carmine St, New York, NY 10014, USA",            "phones": [              "+1 212-366-1182"            ],            "url": null          },          "syncStatus": null        }      ]    }  }}

200A failed scan. `failure` has the code and message, and `results` is empty.

Response

{  "data": {    "listingScan": {      "id": "TGlzdGluZ1NjYW46ZGVkZTNhOTgtNDA5Ni00ZDI3LWJlMjUtMzY3YTYxOTk4Y2Y1",      "status": "FAILED",      "source": "DIRECTORY_SEARCH",      "locationId": null,      "resultsAsOf": null,      "createdAt": "2026-11-03T08:53:18Z",      "startedAt": null,      "completedAt": "2026-11-03T08:53:18Z",      "business": {        "name": "Franklin Barbecue",        "street": "900 E 11th St",        "city": "Austin",        "stateIso": "TX",        "postalCode": "78702",        "countryIso": "US",        "phone": "+15126531187"      },      "summary": {        "total": 0,        "found": 0,        "accurate": 0,        "inaccurate": 0,        "notFound": 0,        "pending": 0,        "unavailable": 0      },      "failure": {        "code": "SY83010",        "message": "SY83010: Listing scans are temporarily unavailable, try again later",        "field": null      },      "results": []    }  }}

401Unauthenticated, missing or invalid API key.

404No scan with that ID on this account, or the scan is older than 90 days (`SY83005`).

Response

{  "data": {    "listingScan": null  },  "errors": [    {      "message": "SY83005: Listing scan not found"    }  ]}

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

Returns one scan created by POST /listings/scans, with its summary and a results[] entry for each directory. While the scan is running, results holds what has been checked so far, and some entries may still be PENDING. When status is COMPLETED the results are final.

Use case: reading the report once the webhook arrives. The listing_scan.completed event already includes the full scan, so most integrations need no read at all. Use this endpoint to re-read a scan later, to show it in a dashboard, or to recover if a webhook was missed.

Use case: polling when webhooks are not available. Read the scan every 15 seconds until status is COMPLETED or FAILED. Do not poll faster: each read counts toward your rate limit. Scans are kept for 90 days; after that this endpoint returns 404 with SY83005.

Scan statuses

`status`	Terminal	Means
`QUEUED`	no	Accepted, not started. `results` is empty.
`IN_PROGRESS`	no	Directories are being checked. `results` fills in as it goes.
`COMPLETED`	yes	Every directory was checked. The results are final.
`FAILED`	yes	The scan could not run. Read `failure`. It did not use your allowance.

The scan object

Field	Type	Description
`id`	string	The scan ID. Use it on this endpoint.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` or `FAILED`.
`source`	string	Where the results came from: `DIRECTORY_SEARCH` (a fresh search), `RECENT_SCAN` (a copy of an identical business scanned by anyone in the last 7 days) or `LOCATION_LISTINGS` (the business matched one of your own locations).
`locationId`	string or null	The matching location. Set only when `source` is `LOCATION_LISTINGS`.
`resultsAsOf`	string or null	When the directory data was collected. For a `RECENT_SCAN` copy this is earlier than `createdAt`. `null` until results exist.
`createdAt`	string	When the scan was created.
`startedAt`	string or null	When the directory checks began.
`completedAt`	string or null	When the scan reached `COMPLETED` or `FAILED`.
`business`	object	The business that was scanned: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` and `phone`. The phone is returned in international format.
`summary`	object	Counts across the results: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` and `unavailable`.
`failure`	object or null	Set when `status` is `FAILED`: `code`, `message` and, when one input field caused it, `field`.
`results`	array	One entry per directory. Empty on a failed scan.

summary.found counts directories where the business is listed. Of those, accurate counts the ones whose details match and inaccurate the ones that do not. A found listing that was confirmed without a field-by-field check is in found only, which is why accurate plus inaccurate can be lower than found.

A result

Field	Type	Description
`directory`	object	The directory: `id`, `name` and `url`. The `id` matches the site ID used elsewhere in the API.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` or `PENDING`.
`accurate`	boolean or null	Whether the listing matches the business. See below.
`accuracySource`	string	How accuracy was decided: `DIRECTORY_MATCH` (the listing was compared with the business) or `SYNC_STATUS` (taken from your own location's sync state).
`accuracy`	object or null	The check per field: `name`, `address` and `phone`, each `{ status, message }`. `null` when there is no listing or no comparison.
`listing`	object or null	What the directory shows: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` and `url`. Fields the directory does not publish are `null`. `null` when not found.
`syncStatus`	string or null	Your own location's sync state on this directory. Set only on `LOCATION_LISTINGS` scans.

Result status

Value	Means
`FOUND`	The business is listed on this directory.
`NOT_FOUND`	The directory was checked and the business is not listed.
`UNAVAILABLE`	This directory could not be checked this time. It does not mean the business is not listed.
`PENDING`	Not checked yet. Only seen while the scan is running.

accurate

Value	Means
`true`	A found listing whose checked details all match the business.
`false`	A found listing where at least one field is wrong. Read `accuracy` to see which.
`null`	No verdict. Either the business was not found, or it was found and the presence was confirmed without a field-by-field check, as for some directories and for AI assistants. These count in `found` only.

accuracy per field. Each of name, address and phone is an object with a status of ACCURATE, INACCURATE or MISSING, and a message that explains a difference, for example Phone number does not match. MISSING means the directory does not show that detail, for example No phone number on the listing. Use listing to display what the directory actually holds next to what you expected.

syncStatus. On a LOCATION_LISTINGS scan the verdict comes from your location's real listing rather than from a comparison. syncStatus is that listing's state (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE or CANNOT_SUBMIT), the same values as GET /locations/{locationId}/listings/premium. SYNCED and COMPLETED count as accurate.

Notes.

A scan only returns for the account that created it. Any other ID answers 404 with SY83005.
Some directories show another directory's data. For example Uber, Waze and Lyft show Google Maps data, and CopilotAI shows Bing data. Their result mirrors the source directory and has no listing url of its own.
Do not treat UNAVAILABLE as a negative: the directory could not be checked, so the answer is unknown.
When the scan is a RECENT_SCAN copy, resultsAsOf is when the data was collected, and createdAt is when it was copied to your account.

Request

curl -X GET 'https://listingsapi.com/api/v4/listings/scans/<scanId>' \  -H "Authorization: API $LISTINGSAPI_KEY"

Run in playground