Get a Batch Operation

Before You Begin

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

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

Why this use case

batchUpsert and batchOperations both hand back a batch's public id (a UUID). When you already have that id, batchOperation loads that one batch — its status, item count, and result file — without paging the repo list.

Availability

batchOperation is a Service Account only operation and is served behind the batch operations feature flag (enable_batch_operations). 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 query will fail validation.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated). The query rejects any non-service-account caller.
Permissions: Your Service Account must be able to create/update cards in the pipe or database that owns the batch (the same permission batchUpsert requires). The batch's repo must belong to the caller's organization.
IDs: The batch operation's id (a UUID) returned by batchUpsert or listed by batchOperations.

Step 1: Run the query

query GetBatchOperation($id: ID!) {
  batchOperation(id: $id) {
    id
    operationType
    status
    totalCount
    createdAt
    finishedAt
    requestedBy {
      id
      name
    }
    resultFile
    suppressAutomations
    suppressWebhooks
  }
}

Variables

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

id (required): the public identifier (UUID) of the batch operation.

Step 2: Check the response

{
  "data": {
    "batchOperation": {
      "id": "8f3b1c9e-2a4d-4c7b-9f10-1d2e3a4b5c6d",
      "operationType": "upsert_records",
      "status": "processing",
      "totalCount": 1500,
      "createdAt": "2026-07-23T12:00:00Z",
      "finishedAt": null,
      "requestedBy": {
        "id": "1234567",
        "name": "Integration Bot"
      },
      "resultFile": null,
      "suppressAutomations": false,
      "suppressWebhooks": false
    }
  }
}

Returned fields

Field	Description
`id`	Public identifier of the batch operation (a UUID)
`operationType`	The kind of batch operation (`upsert_records` or `export_data`)
`status`	Current lifecycle status (see List Batch Operations of a Repo)
`totalCount`	Number of items in the batch
`createdAt`	When the batch was submitted
`finishedAt`	When the batch finished; `null` while it is not finished
`requestedBy`	The user who submitted the batch; `null` if that user no longer exists
`resultFile`	Result file produced by the batch; `null` until the batch produces one
`suppressAutomations`	Whether automations were suppressed for this batch
`suppressWebhooks`	Whether webhooks were suppressed for this batch

Key Notes

An unknown id, an id that is not a UUID, or a batch that belongs to another organization returns null for batchOperation (no error). The query does not reveal whether a batch exists outside the caller's organization.
A caller that is not a Service Account, or a Service Account without create/update card permission on the batch's repo, receives a PERMISSION_DENIED error.
To list every batch of a repo, use batchOperations. To submit a batch and obtain the id used here, use batchUpsert.