Debug Batch

Inspect batch state to diagnose stuck or slow dispatching

Endpoint

GET https://api.graine.ai/api/v1/batches/{batch_id}/debug

Returns diagnostic information about a batch’s internal state. Use this when a batch is in_progress but calls don’t seem to be going out.

Path Parameters

Parameter	Type	Required	Description
batch_id	string	Yes	Batch to inspect

Headers

Header	Required	Description
Authorization	Yes	Bearer gat_<token>

Example Request

curl "https://api.graine.ai/api/v1/batches/btc_xyz001/debug" \
  -H "Authorization: Bearer gat_your_token"

Response

200 OK — Healthy batch

{
  "batch_id": "btc_xyz001",
  "status": "in_progress",
  "status_breakdown": {
    "pending": {
      "count": 22,
      "oldest_updated_at": "2026-05-10T09:05:00Z"
    },
    "dispatched": {
      "count": 3,
      "oldest_updated_at": "2026-05-10T10:28:00Z"
    },
    "completed": {
      "count": 58,
      "oldest_updated_at": "2026-05-10T10:25:00Z"
    }
  },
  "pending_sample": [
    "con_111",
    "con_112",
    "con_113"
  ],
  "diagnostics": {
    "stuck_pending": false,
    "tip": "Batch is healthy — contacts are being dispatched normally."
  }
}

200 OK — Stuck batch

{
  "batch_id": "btc_xyz001",
  "status": "in_progress",
  "status_breakdown": {
    "pending": {
      "count": 78,
      "oldest_updated_at": "2026-05-10T08:00:00Z"
    },
    "dispatched": { "count": 0 },
    "completed": { "count": 22 }
  },
  "pending_sample": [
    "con_201",
    "con_202",
    "con_203"
  ],
  "diagnostics": {
    "stuck_pending": true,
    "tip": "78 contacts have been pending for over 30 minutes with no dispatching activity. The worker is likely down or disconnected from Kafka. Restart the worker, then POST to /batches/btc_xyz001/dispatch to re-trigger."
  }
}

Response Fields

Field	Description
status_breakdown	Per-status contact count and oldest_updated_at timestamp
pending_sample	Up to 3 oldest contact_ids in PENDING state — useful for grepping worker logs
diagnostics.stuck_pending	true if pending contacts have stale timestamps (>30 min with no progress)
diagnostics.tip	Human-readable next step to fix the issue

How to Interpret Results

stuck_pending: true — worker down

Cause: The Apollo worker container is not running or not connected to Kafka, so PENDING contacts are never being consumed and dispatched.

Fix:

1. Restart the worker container
2. Wait ~30 seconds for it to reconnect
3. POST to /batches/{id}/dispatch to re-publish pending contacts

All contacts stuck in dispatched (never complete)

Cause: The telephony provider (RotaryRouter / Jambonz) is accepting calls but not sending status webhooks back to Apollo.

Fix:

1. Check RotaryRouter logs for webhook delivery failures
2. Verify the APOLLO_WEBHOOK_URL env var in RotaryRouter points to Apollo’s /webhooks/call-status
3. Check network connectivity between RotaryRouter and Apollo

High no_answer count

Cause: Contacts aren’t answering. Could be time-of-day, invalid numbers, or carrier blocking.

Fix:

• Review working_hours configuration — are you calling at the right time?
• Check if specific area codes or number ranges are failing
• Consider reducing concurrency to avoid appearing as spam

Batch completed but count looks wrong

Cause: Counters might show stale data from the batch document.

Fix: Counters in GET /batches/{id} are always computed live. If they look wrong, compare with GET /batches/{id}/contacts status breakdown to see the ground-truth per-contact status.

Next Steps

Force Dispatch

Re-publish pending contacts to Kafka

Get Batch

Check current batch status and counters