Get a batch run's progress

GET/v1/invitation_batches/{batch}

Retrieves a run’s progress: its status, how many recipients stand in each state, and when the rest are projected to finish.

Behavior

One call regardless of run size: the cost does not grow with the recipient count.
counts always carries all five states, zeros included, and always sums to recipient_count.
eta is an estimate from a rate that moves, and is absent rather than zero when none can honestly be quoted.
Unknown ids, and another brand’s; return HTTP 404, the same answer.

Path ParametersExpand Collapse

batch: string

ReturnsExpand Collapse

id: string

Run id (invb_…).

accepted_count: number

How many recipients the run will attempt: recipient_count minus the rows the submit screen skipped. The same number the submit response returned, and frozen with it.

formatint32

counts: object { cancelled, failed, pending, 2 more }

How many of a run’s recipients stand in each state. EVERY key is always present, zero included: a client reads five numbers instead of branching on which keys exist, and a state that has not happened yet is 0 rather than missing.

cancelled: number

Stopped by a cancel before it was attempted.

formatint32

failed: number

Accepted at submit, then permanently refused before sending; consent withdrawn in between, a superseded or closed chat, a revoked template grant. The row’s reason says which.

formatint32

pending: number

Not yet attempted. This is the number the ETA projects.

formatint32

sent: number

Handed to the invitation pipeline: an invitation_id exists on that row. Delivery to Apple is reported by that invitation’s own status and webhooks, not here.

formatint32

skipped: number

Dropped by the SUBMIT screen under on_invalid: skip_invalid, with the reason the submit response gave. Frozen at creation; nothing later moves a row into or out of it.

formatint32

created_at: string

formatdate-time

recipient_count: number

How many recipients the run was SUBMITTED with, frozen at creation; dropped rows included. Always the length of the array you sent, and always counts’ total.

formatint32

status: "queued" or "running" or "completed" or "cancelled"

queued (created, nothing attempted yet) → running (at least one recipient attempted, some still pending) → completed (no recipient is pending; every one is sent, failed, cancelled or skipped), or cancelled when you stopped it. completed does NOT mean every invitation was delivered: it means the run has nothing left to attempt, and per-row outcomes are in counts and the recipient results.

One of the following:

"queued"

"running"

"completed"

"cancelled"

template_id: string

updated_at: string

Last change to the run row itself (its status). NOT bumped by a per-recipient transition, so it is a run-lifecycle timestamp and not a progress heartbeat; read counts for progress.

formatdate-time

eta: optional object { at, queued_ahead, rate_per_second, 2 more }

The completion estimate. Absent when none can honestly be quoted; see the model.

at: string

The same estimate as a timestamp on OUR clock; seconds from when this response was composed, so a client does not have to correct for its own skew.

formatdate-time

queued_ahead: number

How many other invitations of yours are queued ahead of this run’s remaining rows in the same brand queue. A run does not clear in isolation; another campaign submitted first is counted here, and so are this run’s own recipients that have already been handed to the delivery queue.

formatint64

rate_per_second: number

Recipients per second the estimate was taken at: min(your brand's effective rate, our overall rate / active brands).

formatdouble

remaining: number

How many of this run’s recipients the estimate covers; counts.pending.

formatint32

seconds: number

Estimated seconds until the last remaining recipient is released. 0 when nothing is pending.

formatint64

not_before: optional string

The run’s scheduled start, if you gave it one. A queued run with a not_before in the future is waiting for its own schedule, not for us.

formatdate-time

spread_over_seconds: optional number

The run’s smoothing window, if you gave it one.

formatint32

Get a batch run's progress

curl https://messages.api.linqapp.com/v1/invitation_batches/$BATCH \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY"

{
  "id": "invb_0d5c19",
  "status": "running",
  "template_id": "invt_a4f2c718d0",
  "recipient_count": 2,
  "accepted_count": 2,
  "counts": {
    "pending": 1,
    "sent": 1,
    "failed": 0,
    "cancelled": 0,
    "skipped": 0
  },
  "created_at": "2026-08-06T14:00:00Z",
  "updated_at": "2026-08-06T14:00:07Z"
}

Returns Examples

{
  "id": "invb_0d5c19",
  "status": "running",
  "template_id": "invt_a4f2c718d0",
  "recipient_count": 2,
  "accepted_count": 2,
  "counts": {
    "pending": 1,
    "sent": 1,
    "failed": 0,
    "cancelled": 0,
    "skipped": 0
  },
  "created_at": "2026-08-06T14:00:00Z",
  "updated_at": "2026-08-06T14:00:07Z"
}