Polling job status

Why polling

Submitting URLs for crawling or checking thousands of them in Google takes from minutes to hours. An API cannot keep the request open that long, so it returns a job ID right away and exposes a status endpoint. Without webhooks, the client asks that endpoint at intervals until the job is done. That is the model for the IndexChex API, published alongside this handbook, and for most other backlink indexer APIs.

Status values

Both v1 job types report a status string:

Treat any value you do not recognise as non-terminal and log it, rather than crashing the loop.

What the status endpoints return

A submission job:

curl https://indexchex.com/api/v1/index-submit/jobs/48211 \
  -H "Authorization: $INDEXCHEX_API_KEY" -H "Accept: application/json"

{
  "job_id": 48211,
  "status": "completed",
  "total_urls": 2,
  "submitted_urls": 2,
  "successful_count": 2,
  "failed_count": 0,
  "progress_percent": 100,
  "success_percent": 100,
  "completed_at": "2026-10-08T09:41:10+00:00",
  "scheduled_check_days": 3,
  "scheduled_check_status": "pending",
  "scheduled_check_at": "2026-10-11T09:14:02+00:00",
  "scheduled_check_run_id": null
}

The check job endpoint returns checked_urls, indexed_count, not_indexed_count, failed_count, progress_percent and completed_at in the same style. Its report is a separate call, covered in checking index status via an API.

Following a scheduled check

When a submission was created with checker set to 1 to 5, its status response carries the follow-up check. scheduled_check_status changes as the check runs, and once it has started scheduled_check_run_id holds the ID of an ordinary index-check job. Poll or fetch that ID on the check endpoints:

GET /api/v1/index-check/jobs/{scheduled_check_run_id}/report

This turns one submission call into a full submit-then-verify cycle with nothing to schedule on the client side except a daily poll.

Picking an interval

All calls share one limit of 120 requests per minute per user. A script polling 20 jobs every 10 seconds already uses all of it. Poll many jobs on a single timer, staggered, rather than one loop per job; rate limits and batching shows the arithmetic.

Python poller with back-off

import os, time, requests

API = "https://indexchex.com/api/v1"
H = {"Authorization": os.environ["INDEXCHEX_API_KEY"], "Accept": "application/json"}
TERMINAL = {"completed", "failed"}

def wait_for(kind, job_id, start=15, ceiling=300, deadline_s=86400):
    """kind is 'index-submit' or 'index-check'."""
    delay, waited = start, 0
    while waited < deadline_s:
        r = requests.get(f"{API}/{kind}/jobs/{job_id}", headers=H, timeout=30)
        if r.status_code == 429:
            delay = min(delay * 2, ceiling)
        else:
            r.raise_for_status()
            body = r.json()
            if body["status"] in TERMINAL:
                return body
            delay = min(int(delay * 1.5), ceiling)
        time.sleep(delay)
        waited += delay
    raise TimeoutError(f"{kind} job {job_id} still running after {waited}s")

done = wait_for("index-check", 90314)
print(done["indexed_count"], "of", done["total_urls"], "indexed")

The delay grows by half after each unfinished poll and doubles after a 429, capped at five minutes. Error branches beyond 429 are covered in handling API errors.

Polling on v2

SpeedyIndex-compatible clients poll with POST /v2/task/google/{type}/status and a task_id, or several at once with task_ids, and stop when is_completed is true. Batching IDs into one call saves requests when many tasks are open. For indexer tasks created with checker, is_completed stays false until the scheduled check has finished. Details are in migrating a SpeedyIndex integration.

Persist state between runs

Store each job ID with its creation time and kind, and mark it done only after the final result has been saved. A cron-driven poller that restarts can then pick up open jobs without resubmitting anything. Jobs created via the submission endpoint are also visible in the dashboard, which helps when reconciling.

Related

Polling is one of the features that distinguish scripted tools from dashboard-only ones; see what backlink indexer software is. Account-level API facts are on the IndexChex entry.