/api/v4/listings/scansسرد listings scans
يعيد listings scans الخاصة بالحساب، من الأحدث إلى الأقدم، دون نتائج كل دليل، مع تفاصيل تقسيم النتائج إلى صفحات والحصة الشهرية.
المعلمات
الاستعلام
| الاسم | النوع | مطلوب | الوصف | الافتراضي |
|---|---|---|---|---|
| page | integer | اختياري | Page number, starting at 1. | 1 |
| perPage | integer | اختياري | 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.
{ "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، أي موعد إعادة تعيين الحصة التالي. اقرأه قبل تنفيذ مجموعة من عمليات الإنشاء لمعرفة عدد الفحوصات الجديدة التي لا يزال بإمكانك إنشاؤها. تكون قيمته null عندما لا تكون للحساب حصة، مثلًا عند الاشتراك في خطة لا تتضمن listings scans.
تقسيم النتائج إلى صفحات
يبدأ page من 1، والقيمة الافتراضية لـ perPage هي 20. يوضح pageInfo موضعك الحالي: totalRecords وtotalPages وhasNextPage وhasPreviousPage. اطلب الصفحات بالترتيب وتوقف عندما تكون قيمة hasNextPage هي false.
ملاحظات.
- يُحتفظ بالفحوصات لمدة 90 يومًا. لا تُعاد الفحوصات الأقدم من ذلك.
- تكون مصفوفة
scansفارغة عندما لا يحتوي الحساب على أي فحوصات بعد. - تُحتسب قراءة القائمة طلبًا واحدًا ضمن حد معدل الطلبات. لا تستخدمها لانتظار فحص: اقرأ ذلك الفحص مباشرةً، أو استخدم webhook الخاص بـ
listing_scan.completed.
curl -X GET 'https://listingsapi.com/api/v4/listings/scans' \ -H "Authorization: API $LISTINGSAPI_KEY"