Listings APIListings API
로그인
GET/api/v4/listings/scans

listings scans 목록 조회

계정의 listings scans를 최신순으로 반환하며, 디렉터리별 결과는 제외하고 페이지네이션 정보와 월간 사용 한도를 함께 제공합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

쿼리

이름유형필수설명기본값
pageinteger선택Page number, starting at 1.1
perPageinteger선택Scans per page, from 1 to 50. Values outside that range are brought back to it.20

응답

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.

계정에서 생성한 스캔을 최신순으로 나열합니다. 각 항목에는 GET /listings/scans/{scanId}과 동일한 필드가 있지만, results는 포함되지 않습니다. 각 항목의 summary에는 집계 수치가 있으며, 전체 결과를 읽으려면 해당 항목의 id를 GET /listings/scans/{scanId}에 전달하세요.

사용 사례: 감사 이력. 팀에서 실행한 스캔을 각각의 비즈니스, 상태, summary와 함께 표시하세요. 각 행을 GET /listings/scans/{scanId}을 기반으로 만든 스캔 페이지에 연결하세요.

사용 사례: 생성 전 허용량 확인. quota는 요금제의 월별 허용량 정보인 limit, used, remaining 및 다음 허용량 초기화 시점인 resetsAt를 제공합니다. 생성을 일괄 실행하기 전에 이 정보를 읽어 새로 생성할 수 있는 스캔이 몇 개 남았는지 확인하세요. listings scans가 포함되지 않은 요금제를 사용하는 경우처럼 계정에 허용량이 없으면 이 값은 null입니다.

페이지 나누기

page는 1부터 시작하며 perPage의 기본값은 20입니다. pageInfo는 현재 페이지 위치를 나타내는 totalRecords, totalPages, hasNextPage, hasPreviousPage를 제공합니다. 페이지를 순서대로 요청하고 hasNextPage가 false이면 중단하세요.

참고 사항.

  • 스캔은 90일 동안 보관됩니다. 그보다 오래된 스캔은 반환되지 않습니다.
  • 계정에 아직 스캔이 없으면 scans 배열은 비어 있습니다.
  • 목록을 읽으면 요청 빈도 제한에서 요청 1회가 차감됩니다. 스캔이 완료될 때까지 기다리는 용도로 이 목록을 사용하지 마세요. 해당 스캔을 직접 읽거나 listing_scan.completed 웹훅을 사용하세요.
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground