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

Listar listings scans

Retorna os listings scans da conta, do mais recente ao mais antigo, sem resultados por diretório, com detalhes de paginação e a cota mensal.

Requer uma chave de API. Consulte Autenticação para ver o formato do cabeçalho e a rotação de chaves.

Parâmetros

Query

NomeTipoObrigatórioDescriçãoPadrão
pageintegeropcionalPage number, starting at 1.1
perPageintegeropcionalScans per page, from 1 to 50. Values outside that range are brought back to it.20

Respostas

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.

Lista as varreduras criadas pela sua conta, da mais recente para a mais antiga. Cada item tem os mesmos campos de GET /listings/scans/{scanId}, exceto que results não é incluído. O campo summary de cada item contém as contagens; passe o valor de id desse item para GET /listings/scans/{scanId} para consultar os resultados completos.

Caso de uso: histórico de auditorias. Mostre as varreduras executadas pela sua equipe, cada uma com a empresa, o status e summary correspondentes. Vincule cada linha à página de varredura que você criar com base em GET /listings/scans/{scanId}.

Caso de uso: consultar a cota antes de criar. quota informa a cota mensal do seu plano: limit, used, remaining e resetsAt, que indica quando a cota será renovada. Consulte esse campo antes de um lote de criações para verificar quantas novas varreduras você ainda pode criar. O valor é null quando a conta não tem cota, por exemplo, em um plano que não inclui listings scans.

Paginação

page começa em 1 e perPage tem o valor padrão 20. pageInfo indica sua posição: totalRecords, totalPages, hasNextPage e hasPreviousPage. Solicite as páginas em ordem e pare quando hasNextPage for false.

Observações.

  • As varreduras são mantidas por 90 dias. Varreduras mais antigas não são retornadas.
  • O array scans fica vazio quando a conta ainda não tem varreduras.
  • Consultar a lista consome uma requisição do seu limite de requisições. Não use a lista para aguardar uma varredura: consulte essa varredura diretamente ou use o webhook listing_scan.completed.
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground