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

Elenca i listings scans

Restituisce i listings scans dell'account dal più recente, senza risultati per directory, con dettagli di paginazione e quota mensile.

Richiede una chiave API. Consulta Autenticazione per il formato dell’header e la rotazione delle chiavi.

Parametri

Query

NomeTipoObbligatorioDescrizionePredefinito
pageintegerfacoltativoPage number, starting at 1.1
perPageintegerfacoltativoScans per page, from 1 to 50. Values outside that range are brought back to it.20

Risposte

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.

Elenca le scansioni create dal tuo account, dalla più recente. Ogni elemento ha gli stessi campi di GET /listings/scans/{scanId}, ma results non è incluso. Il campo summary di ogni elemento contiene i conteggi; passa il suo id a GET /listings/scans/{scanId} per leggere i risultati completi.

Caso d'uso: cronologia degli audit. Mostra le scansioni eseguite dal tuo team, ciascuna con la relativa attività, lo stato e summary. Collega ogni riga alla pagina della scansione che crei usando GET /listings/scans/{scanId}.

Caso d'uso: verifica della quota prima della creazione. quota riporta la quota mensile del tuo piano: limit, used, remaining e resetsAt, che indica quando la quota verrà ripristinata. Leggilo prima di un gruppo di operazioni di creazione per sapere quante nuove scansioni puoi ancora creare. Il valore è null quando l'account non dispone di una quota, ad esempio con un piano che non include listings scans.

Paginazione

page parte da 1 e il valore predefinito di perPage è 20. pageInfo indica la posizione corrente: totalRecords, totalPages, hasNextPage e hasPreviousPage. Richiedi le pagine in ordine e fermati quando hasNextPage è false.

Note.

  • Le scansioni vengono conservate per 90 giorni. Le scansioni più vecchie non vengono restituite.
  • L'array scans è vuoto quando l'account non ha ancora scansioni.
  • La lettura dell'elenco conta come una richiesta ai fini del tuo limite di frequenza. Non usarla per attendere una scansione: leggi direttamente quella scansione oppure usa il webhook listing_scan.completed.
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground