Monitoring a campaign

• GET /v1/campaign/{id}/status — latest run’s progress, polled while live.
• GET /v1/campaign/{id}/analytics — campaign-wide aggregate rollup.
• GET /v1/campaign/{id}/runs/{run_id}/snapshot — frozen execution snapshot (content, sender, channel, cost, recipients).

​

1. Live status — for polling loops

GET https://karibu.briq.tz/v1/campaign/{campaign_id}/status

• Returns the latest run’s execution status plus batch progress counters.
• Mirrors the user-facing /campaigns/{id}/status endpoint shape — the same fields whether you call the developer or the user surface.
• This is the endpoint to poll while a campaign is active.

​

Success response (run exists)

{
  "success": true,
  "data": {
    "campaign_id": "8d2e1f6a-...",
    "campaign_run_id": "run_789",
    "status": "running",
    "current_batch": 1,
    "total_batches": 2,
    "recipient_count": 1500,
    "sent": 1000,
    "failed": 5,
    "skipped": 0,
    "delivered": 800,
    "updated_at": "2026-05-12T09:14:02.218Z"
  },
  "errors": null,
  "request_id": "req_01J..."
}

​

Response when no run yet

{
  "success": true,
  "data": {
    "campaign_id": "8d2e1f6a-...",
    "status": "NO_RUN"
  },
  "errors": null,
  "request_id": "req_01J..."
}

​

Field reference

​

Errors

​

Code samples

curl -X GET "https://karibu.briq.tz/v1/campaign/8d2e1f6a-.../status" \
  -H "X-API-Key: YOUR_API_KEY"

​

Polling cadence

​

2. Aggregate analytics

GET https://karibu.briq.tz/v1/campaign/{campaign_id}/analytics

• Returns campaign-wide aggregate analytics across all runs (delivery rate, failure rate, counts, timing).
• When no analytics row has been written yet (e.g. a campaign created but never run, or polled in the first seconds after launch), the endpoint returns a zeroed-out payload with null rate fields. HTTP status is still 200 — check delivery_rate !== null to know whether percentages are renderable.

​

Success response (populated)

{
  "success": true,
  "data": {
    "campaign_id": "8d2e1f6a-...",
    "campaign_run_id": "run_789",
    "workspace_id": "ws_01J...",
    "total_recipients": 1500,
    "sent_count": 1495,
    "failed_count": 5,
    "skipped_count": 0,
    "cancelled_count": 0,
    "delivered_count": 1400,
    "failed_delivery_count": 95,
    "pending_delivery_count": 0,
    "delivery_rate": 0.9398,
    "failure_rate": 0.0033,
    "first_sent_at": "2026-05-12T09:12:01.001Z",
    "last_sent_at":  "2026-05-12T09:14:48.812Z",
    "completed_at":  "2026-05-12T09:14:59.044Z"
  },
  "errors": null,
  "request_id": "req_01J..."
}

​

Field reference

​

Errors

​

Code samples

curl -X GET "https://karibu.briq.tz/v1/campaign/8d2e1f6a-.../analytics" \
  -H "X-API-Key: YOUR_API_KEY"

​

3. Run detail — composite payload

GET https://karibu.briq.tz/v1/campaign/{campaign_id}/runs/{run_id}

​

Batch fields

​

Recipient fields

​

Errors

​

Code samples

curl -X GET "https://karibu.briq.tz/v1/campaign/8d2e1f6a-.../runs/run_789" \
  -H "X-API-Key: YOUR_API_KEY"

​

Run snapshot (read-only, PII-gated)

GET https://karibu.briq.tz/v1/campaign/{campaign_id}/runs/{run_id}/snapshot

• Returns the engine’s execution_snapshot — the frozen, point-in-time state used to dispatch this run: content, sender, channel, provider, cost, recipient count, and optionally the recipient list.
• Query param ?include_recipients=true opts into returning the recipient phone-number list. Stripped by default.

​

Success response (default, without recipients)

{
  "success": true,
  "data": {
    "run_id": "run_789",
    "campaign_id": "8d2e1f6a-...",
    "recipient_count": 1500,
    "content": {
      "channel": "SMS",
      "provider": "mock",
      "sender_id": "BRIQ",
      "body": "Hello, thanks for joining."
    },
    "cost": {
      "total_cost": 1500,
      "currency_units": "sms_parts"
    },
    "status": "running",
    "started_at": "2026-05-12T09:12:00.118Z",
    "completed_at": null
  },
  "errors": null,
  "request_id": "req_01J..."
}

​

Success response (with ?include_recipients=true)

{
  "success": true,
  "data": {
    "run_id": "run_789",
    "campaign_id": "8d2e1f6a-...",
    "recipient_count": 1500,
    "content": { "...": "..." },
    "cost":    { "...": "..." },
    "recipients": ["255712345678", "255713000111", "..."],
    "status": "running",
    "started_at": "2026-05-12T09:12:00.118Z",
    "completed_at": null
  },
  "errors": null,
  "request_id": "req_01J..."
}

​

Errors

​

Code samples

# Default — no PII
curl -X GET "https://karibu.briq.tz/v1/campaign/8d2e1f6a-.../runs/run_789/snapshot" \
  -H "X-API-Key: YOUR_API_KEY"

# Opt in to the recipient list (server-side only)
curl -X GET "https://karibu.briq.tz/v1/campaign/8d2e1f6a-.../runs/run_789/snapshot?include_recipients=true" \
  -H "X-API-Key: YOUR_API_KEY"

​

What happens after launch

1. Pickup (≤ 30 seconds). A separate worker microservice runs a cron query of campaign_runs WHERE status = 'scheduled' AND scheduled_at <= now(). It claims the row by flipping its status to the internal claimed sentinel. The API translates claimed to running in every response, so you will only ever see running.
2. Batches of 1000. The engine partitions the run’s recipients into batches of up to 1000 and writes a campaign_batches row per partition. Each batch is dispatched through the campaign’s channel + provider; per-recipient rows land in campaign_recipients and messages.
3. Counters roll up. As batches complete, sent_count, failed_count, skipped_count, and delivered_count on the run row are incremented. The parent campaign’s aggregate counters are recomputed off the run’s totals — this is what populates the next /status and /analytics response.
4. Terminal state and analytics. When all batches finish, the run flips to completed (or failed). The engine then writes a campaign_analytics row — at this point /analytics returns its populated payload.
5. Optional refund. If a run failed partway through, or the campaign was cancelled, the engine refunds the unsent portion of the credit reservation. Synchronous on /cancel; reconciler-driven for other failure paths.

​

Practical cadence

• During scheduled / running: poll /status every 5–15 seconds.
• On terminal transition (completed, failed, or cancelled): stop polling, call /analytics once for the final rollup.
• For a run-level UI (drilldown modal, per-recipient list): call /runs/{run_id} for the composite payload. Use the snapshot endpoint only when you need the frozen dispatch state.
• Prefer the dashboard for ad-hoc inspection. Build a poller only when you need automation — e.g. piping data into your own analytics, alerting on failure rates, or driving a custom operator console.

​

Related guides

• Campaigns overview — concepts, lifecycle, and the full endpoint map.
• Launch and control — scheduling, cancelling, and the run lifecycle that this page reports on.