نتایج گوگل

مصرف

اندپوینت مصرف برای شمارش پرس‌وجوها، اجراها و هدف‌ها در یک دورهٔ ماهانه، و فرق شکست با بلاک.

GET /usage می‌گوید در یک دوره چه کرده‌اید. برای داشبورد مصرف، گزارش دوره‌ای، و — مهم‌تر از همه — دیدن نرخ شکست پیش از اینکه خودش را در گزارش‌هایتان نشان دهد.

مصرف یک دوره

GET /usage?period=YYYY-MM — نیازمند usage:read.

شمارنده‌های یک دورهٔ ماهانه. پیش‌فرض دورهٔ جاری است.

نمونهٔ درخواست:

curl -s -H "X-API-Key: $KEY" \
  "https://serp.rasaad.ir/api/v1/operator/usage?period=2026-10"

نمونهٔ پاسخ:

{
  "ok": true,
  "period": "2026-10",
  "queries": 120,
  "completed": 118,
  "failed": 2,
  "blocked": 5,
  "queued": 3,
  "targets": 4,
  "runs": 115,
  "quota": null,
  "remaining": null
}

معنای هر شمارنده

فیلد	یعنی چه
`queries`	تسک‌هایی که در این دوره ساخته شده‌اند
`completed`	آن‌هایی که `status = done` دارند
`failed`	`failed` + `expired`
`blocked`	اجراهایی که جزئیاتشان کپچا ذکر می‌کند
`queued`	`queued` + `claimed`
`targets`	هدف‌های فعالی که دارید
`runs`	اجراهای تمام‌شده‌ای که نتیجه‌شان سند شده
`quota`, `remaining`	همیشه `null`

چهار فرقی که نباید قاطی کنید

این چهار عدد از هم جدا هستند و قاطی کردنشان باعث گزارش غلط می‌شود:

فرق	چرا مهم است
`queries` ≠ `completed`	شامل کارهایی است که هنوز در صف‌اند
`failed` ≠ `blocked`	تایم‌اوت و نتیجهٔ خالی، بلاک نیستند
`completed` ≠ `runs`	یک اجرای کامل می‌تواند هیچ سندی نسازد
`targets` خارج از دوره است	تعداد فعلی، نه تعداد ساخته‌شده در آن ماه

blocked فقط اجراهایی است که دلیلشان کپچا اعلام شده — نه هر شکستی. یک تایم‌اوت یا یک اجرای بدون نتیجه، بلاک نیست. اگر این دو را یکی بگیرید، مشکلی را که قابل حل نیست (کپچا) با مشکلی که قابل حل است (تایم‌اوت) اشتباه می‌گیرید.

نرخ شکست را خودتان حساب کنید

failed بر queries تقسیم می‌شود، ولی حواستان باشد صورت و مخرج چیست:

نسبت	یعنی چه	چه چیزی می‌گوید
`completed / queries`	وضعیت کلی صف	آیا کارها به‌جای می‌رسند
`blocked / completed`	نرخ کپچا	آیا جستجوهای شما سالم مانده‌اند

completed / queries را تنها سنجهٔ سلامت نگیرید. اگر تقریباً همه‌چیز کپچا بخورد، وضعیت کلی خوب به نظر می‌رسد در حالی که عملاً هیچ دادهٔ قابل استفاده‌ای ندارید. عدد blocked را هم نگاه کنید — در نتایج، فلگ flags.blocked همین را در هر اجرا نشان می‌دهد.

چرا `quota` و `remaining` همیشه `null` هستند

این دو همیشه null هستند. نه به‌خاطر نبودن پیاده‌سازی، بلکه چون این سرویس صورت‌حساب و سقف عددی وجود ندارد.

مقدار 0 هم نگذارید. عدد 0 ادعایی دربارهٔ یک حد است که وجود ندارد — و کلاینتی که آن را می‌بیند، سخت‌افزار هشدار «رسیدیم به سقف» را روشن می‌کند. null یعنی «سقفی در کار نیست»، که صادقانه است.

تنها محدودیت عملی شما، محدودیت نرخ است، نه سقف ماهانه. سطل توکن را در کلاینت خودتان نگه دارید و برای 429 آماده باشید.

دوره‌ها را مقایسه کنید

period اجازه می‌دهد دوره‌های گذشته را هم بخوانید، پس می‌توانید روند ببینید:

for p in 2026-08 2026-09 2026-10; do
  printf '%s ' "$p"
  curl -s -H "X-API-Key: $KEY" \
    "https://serp.rasaad.ir/api/v1/operator/usage?period=$p" \
    | jq -c '{queries, completed, failed, blocked, runs}'
done

دنبال چه باشید	چه معنایی دارد
رشد `blocked`	جستجوهای شما دارند به سمت کپچا می‌روند
اختلاف `queries` و `runs`	اجراهایی که به سند نمی‌رسند
رشد `targets` بدون رشد `runs`	هدف‌ها ساخته شده ولی اجرا نمی‌شوند
`queued` بالای ماندگار	یا پردازش کند شده یا شما بیش از توان سرویس می‌خواهید

قدم بعدی:محدودیت نرخ. queued بالا معمولاً یعنی به سقف نرخ خورده‌اید — و نحوهٔ رفتار درست با 429 آنجا توضیح داده شده است.

نتایج

محدودیت نرخ