Listings APIListings API
Iniciar sesión
GET/api/v4/listings/scans

Listar listings scans

Devuelve los listings scans de la cuenta del más reciente al más antiguo, sin resultados por directorio, con detalles de paginación y el cupo mensual.

Requiere una clave de API. Consulta Autenticación para conocer el formato del encabezado y la rotación de claves.

Parámetros

Consulta

NombreTipoObligatorioDescripciónPredeterminado
pageintegeropcionalPage number, starting at 1.1
perPageintegeropcionalScans per page, from 1 to 50. Values outside that range are brought back to it.20

Respuestas

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.

Enumera los escaneos que ha creado tu cuenta, del más reciente al más antiguo. Cada elemento tiene los mismos campos que GET /listings/scans/{scanId}, excepto que no se incluye results. El campo summary de cada elemento contiene los recuentos; pasa su id a GET /listings/scans/{scanId} para consultar los resultados completos.

Caso de uso: un historial de auditorías. Muestra los escaneos que ha ejecutado tu equipo, cada uno con su negocio, estado y summary. Enlaza cada fila a la página del escaneo que crees a partir de GET /listings/scans/{scanId}.

Caso de uso: comprobar el cupo antes de crear un escaneo. quota indica el cupo mensual de tu plan: limit, used, remaining y resetsAt, que indica cuándo se restablece el cupo por próxima vez. Consúltalo antes de un lote de operaciones de creación para saber cuántos escaneos nuevos puedes crear todavía. Su valor es null cuando la cuenta no tiene cupo, por ejemplo, en un plan que no incluye listings scans.

Paginación

page empieza en 1 y el valor predeterminado de perPage es 20. pageInfo indica en qué punto estás: totalRecords, totalPages, hasNextPage y hasPreviousPage. Solicita las páginas en orden y detente cuando hasNextPage sea false.

Notas.

  • Los escaneos se conservan durante 90 días. No se devuelven los escaneos más antiguos.
  • El array scans está vacío cuando la cuenta aún no tiene escaneos.
  • Consultar la lista consume una solicitud de tu límite de solicitudes. No la uses para esperar a que termine un escaneo: consulta ese escaneo directamente o usa el webhook listing_scan.completed.
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground