List Batch Operations of a Repo

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

The batchOperations query lists the batch operations submitted against a single repo (a pipe or a database) through batchUpsert. Because batchUpsert runs asynchronously, use batchOperations to poll the progress of your submissions and to retrieve each batch's current status, item count, and result file.

Availability

batchOperations 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 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 target pipe or database (the same permission batchUpsert requires).
IDs: See our Get resource IDs page for how to find the repoId (pipe or database ID).

Step 1: Run the query

query ListBatchOperations($repoId: ID!, $status: BatchOperationStatus, $first: Int, $after: String) {
  batchOperations(repoId: $repoId, status: $status, first: $first, after: $after) {
    edges {
      node {
        id
        operationType
        status
        totalCount
        resultFile
        createdAt
        finishedAt
        suppressAutomations
        suppressWebhooks
        requestedBy {
          id
          name
        }
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Variables

{
  "repoId": "301234567",
  "status": "processing",
  "first": 20
}

repoId (required): the pipe or database whose batch operations are listed.
status (optional): restrict the result to a single lifecycle status. Omit it to list every batch of the repo.
first / after (optional): standard Relay cursor pagination. Pass the previous page's pageInfo.endCursor as after to fetch the next page.

Step 2: Check the response

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

Returned fields

Field	Description
`edges[].node.id`	Public identifier of the batch operation (a UUID)
`edges[].node.operationType`	The kind of batch operation (`upsert_records`)
`edges[].node.status`	Current lifecycle status (see the table below)
`edges[].node.totalCount`	Number of items in the batch
`edges[].node.resultFile`	Result file produced by the batch; `null` until the batch produces one
`edges[].node.createdAt`	When the batch was submitted
`edges[].node.finishedAt`	When the batch finished; `null` while it is not finished
`edges[].node.suppressAutomations`	Whether automations were suppressed for this batch
`edges[].node.suppressWebhooks`	Whether webhooks were suppressed for this batch
`edges[].node.requestedBy`	The user who submitted the batch; `null` if that user no longer exists
`pageInfo.endCursor`	Cursor of the last returned batch — pass it as `after` to fetch the next page
`pageInfo.hasNextPage`	Whether more batches exist beyond this page

Status values

status (both the argument and the returned field) uses the BatchOperationStatus enum:

Value	Meaning
`queued`	Submitted, not yet loaded
`pending`	Items loaded, ready for processing
`processing`	Processing in progress
`completed`	Finished with no item errors
`completed_with_errors`	Finished with some item errors
`failed`	Failed

Key Notes

Results are ordered by createdAt descending (most recently submitted first).
The query is scoped to the given repoId and never returns batches from another repo or organization.
A caller that is not a Service Account, or a Service Account without permission on the target repo, receives a PERMISSION_DENIED error. A repo that does not exist returns the same PERMISSION_DENIED message, so the query does not reveal whether a given repo exists.
To submit a batch and obtain the IDs listed here, use the batchUpsert mutation.
A known batch id can be read with batchOperation instead of paging this list.