Listings APIListings API
Anmelden
GET/api/v4/listings/scans

listings scans auflisten

Gibt die listings scans des Kontos zurück, neueste zuerst, ohne Ergebnisse je Verzeichnis, mit Paginierungsdetails und monatlichem Kontingent.

Erfordert einen API-Schlüssel. Format des Headers und Schlüsselrotation finden Sie unter Authentifizierung.

Parameter

Query

NameTypErforderlichBeschreibungStandard
pageintegeroptionalPage number, starting at 1.1
perPageintegeroptionalScans per page, from 1 to 50. Values outside that range are brought back to it.20

Antworten

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.

Listet die Scans auf, die Ihr Konto erstellt hat, beginnend mit den neuesten. Jedes Element enthält dieselben Felder wie GET /listings/scans/{scanId}, allerdings ohne results. summary enthält für jedes Element die Anzahlen; übergeben Sie dessen id an GET /listings/scans/{scanId}, um die vollständigen Ergebnisse abzurufen.

Anwendungsfall: Verlauf der Prüfungen. Zeigen Sie die Scans an, die Ihr Team ausgeführt hat, jeweils mit dem zugehörigen Unternehmen, dem Status und summary. Verlinken Sie jede Zeile mit der Scan-Seite, die Sie auf Grundlage von GET /listings/scans/{scanId} erstellen.

Anwendungsfall: Kontingent vor dem Erstellen prüfen. quota gibt das monatliche Kontingent Ihres Tarifs an: limit, used, remaining und resetsAt, den Zeitpunkt der nächsten Zurücksetzung des Kontingents. Rufen Sie es vor einer Reihe von Erstellungsaufrufen ab, um zu sehen, wie viele neue Scans Sie noch erstellen können. Der Wert ist null, wenn das Konto kein Kontingent hat, beispielsweise bei einem Tarif, der keine listings scans enthält.

Seitennavigation

page beginnt bei 1 und perPage hat den Standardwert 20. pageInfo zeigt Ihnen, wo Sie sich befinden: totalRecords, totalPages, hasNextPage und hasPreviousPage. Rufen Sie die Seiten der Reihe nach ab und beenden Sie den Abruf, wenn hasNextPage den Wert false hat.

Hinweise.

  • Scans werden 90 Tage lang aufbewahrt. Ältere Scans werden nicht zurückgegeben.
  • Das Array scans ist leer, wenn das Konto noch keine Scans hat.
  • Der Abruf der Liste wird als eine Anfrage auf Ihr Anfragelimit angerechnet. Verwenden Sie ihn nicht, um auf einen Scan zu warten: Rufen Sie diesen Scan direkt ab oder verwenden Sie den Webhook listing_scan.completed.
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground