List running backfills

GET

/v1/backfills

curl --request GET \
  --url 'https://api.inboxcnx.com/v1/backfills?include=total' \
  --header 'Authorization: Bearer <token>'

Lists the running backfills of all the application’s grants, newest first, so an embedding app can show an import in progress for every grant with one call. Keyset pagination.

kind: "history" is a backfill the Application started. kind: "catch_up" is one InboxCNX started to deliver mail a grant missed while it was held back (a message limit, a pause or a block). It has no estimate and cannot be cancelled.

Requires the write:connections scope.

Authorizations

• apiKey

Parameters

Query Parameters

cursor

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

string

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

limit

Page size, between 1 and 200. Default 50.

integer

>= 1 <= 200

Page size, between 1 and 200. Default 50.

include

total adds the number of matching results, counted up to 10000.

string

Allowed values: total

total adds the number of matching results, counted up to 10000.

Responses

200

A page of running backfills

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string format: uuid

grantId

required

string format: uuid

kind

required

string

Allowed values: history catch_up

since

required

string | null

until

required

string | null

roles

required

Array<string> | null

labels

required

Array<string> | null

status

required

string

Allowed values: running done cancelled

waitingReason

required

string | null

listed

required

integer

published

required

integer

estimatedMessages

required

integer | null

createdAt

required

string

finishedAt

required

string | null

nextCursor

required

Pass back as cursor for the next page. Null on the last page.

string | null

prevCursor

required

Pass back as cursor for the previous page. Null on the first page.

string | null

total

Present only when requested with include. exact is false once the count reaches 10000 (or the depth cap of a relevance search); count is then that cap.

object

count

required

integer

exact

required

boolean

Example

{
  "data": [
    {
      "id": "7c1d9e2a-0b3f-4a5c-8d6e-2f1a0b9c8d7e",
      "grantId": "9b2f0c4e-6a1d-4f3b-8c55-0d7e2a91b3c4",
      "kind": "history",
      "since": "2026-09-20T10:00:00.000Z",
      "until": "2026-10-20T10:00:00.000Z",
      "roles": null,
      "labels": null,
      "status": "running",
      "waitingReason": null,
      "listed": 1200,
      "published": 950,
      "estimatedMessages": 2410,
      "createdAt": "2026-10-20T10:00:00.000Z",
      "finishedAt": null
    }
  ],
  "nextCursor": null,
  "prevCursor": null
}

400

Malformed cursor

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

The credential lacks the write:connections scope

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}