Reprocess the Failed Items of a Batch Operation

Before You Begin

🔗 Use the GraphQL Playground to execute the mutation in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Why this use case

A batchUpsert submission runs asynchronously and can finish with some items in failed status: an item whose match value could not identify a single record, or an item in a chunk that exhausted its processing retries. When a batch finishes as completed_with_errors (or failed), the reprocessBatchOperation mutation resubmits only those failed items, re-running them through the same pipeline without touching the items that already succeeded.

Availability

reprocessBatchOperation is a Service Account only operation and is served behind the batch operations feature flag. The field is present in the schema only for organizations where the feature is enabled; if your organization does not have it enabled, the field will not appear and the mutation will fail validation.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated). The mutation rejects any non-service-account caller.
2. Permissions: Your Service Account must be able to create/update cards in the target pipe or database (the same permission batchUpsert requires).
3. IDs: The batch operation's id (a UUID) returned by batchUpsert or listed by the batchOperations query. See List Batch Operations of a Repo to find it.

Step 1: Run the mutation

mutation ReprocessBatchOperation($input: ReprocessBatchOperationInput!) {
  reprocessBatchOperation(input: $input) {
    batchOperation {
      id
      status
      totalCount
      finishedAt
    }
  }
}

Variables

{
  "input": {
    "id": "8f3b1c9e-2a4d-4c7b-9f10-1d2e3a4b5c6d"
  }
}

• id (required): the public identifier (UUID) of the batch operation whose failed items you want to reprocess.

Step 2: Check the response

{
  "data": {
    "reprocessBatchOperation": {
      "batchOperation": {
        "id": "8f3b1c9e-2a4d-4c7b-9f10-1d2e3a4b5c6d",
        "status": "pending",
        "totalCount": 1500,
        "finishedAt": null
      }
    }
  }
}

Returned fields

Poll the batch with the batchOperations query to follow the reprocessing to completion, exactly as you would after the original submission.

Key Notes

• Only failed items are re-run. Items already in succeeded (or skipped) status are never touched and are never processed a second time.
• Idempotent where it matters. Reprocessing a batch that finished carrying no failed items is a no-op: the batch is returned unchanged and nothing is resubmitted, so a client that retries the call is safe.
• Reprocessable states. Reprocessing applies to a batch that has finished carrying failed items (completed_with_errors or failed). For any other status the mutation returns an INVALID_INPUT error naming the current one: a batch that is queued, pending, or processing has nothing settled to retry, and a completed batch has no failed item to re-run. The same error answers a second call made while a first reprocessing is still running, since that batch is back in pending — only one dispatch happens, and the second caller is told so instead of receiving a payload that looks like a resubmission.
• Scope. The mutation is scoped to your organization and the batch's repo. A batch UUID that does not belong to your organization returns a RESOURCE_NOT_FOUND error, so the mutation does not reveal whether a given batch exists elsewhere.
• Permissions. A caller that is not a Service Account, or a Service Account without permission on the batch's repo, receives a PERMISSION_DENIED error.
• Some failures repeat on purpose. Failures caused by a field marked unique are deterministic and will fail again unless you fix the submission and send a new batch: a row that repeats a value another row of the same submission already used for that field (only the first row is applied; the later ones fail), and a row whose value is already held by another record. Reprocessing them changes nothing, since the condition that caused the failure is still there.
• To submit a new batch, use the batchUpsert mutation; to list batches and their statuses, use the batchOperations query.