> ## Documentation Index
> Fetch the complete documentation index at: https://connectionshub.atlastube.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Bulk Calculate Batch

> Status of a bulk-calculate batch. While it runs, `progressPercent` and `summary` advance and `items` is `null`; the `Location` and `Retry-After` headers say where and how soon to poll. Once `state` is `completed` or `failed`, `items` lists every requested item in request order and the poll headers are gone.



## OpenAPI

````yaml api/openapi.json GET /v1/projects/{projectId}/batches/{batchId}
openapi: 3.1.0
info:
  title: Connections Hub API
  version: 1.0.0
  description: >-
    Run HSS Connections Hub calculators programmatically: create projects,
    create and solve sheets from any calculator template, run batches, and
    export reports to PDF.


    All endpoints require API key authentication.
servers:
  - url: https://api.calcs.com
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: >-
      Create and manage calculation projects. Each user can have multiple
      projects to organize their calculations.
  - name: Sheets
    description: >-
      Manage individual calculation sheets — read one back, update its inputs,
      solve or re-solve it, and delete single sheets or clean up many at once.
  - name: Templates
    description: >-
      Run calculations using any enabled template. Supports all calculator types
      without requiring endpoint-specific code.
paths:
  /v1/projects/{projectId}/batches/{batchId}:
    get:
      tags:
        - Templates
      summary: Get Bulk Calculate Batch
      description: >-
        Status of a bulk-calculate batch. While it runs, `progressPercent` and
        `summary` advance and `items` is `null`; the `Location` and
        `Retry-After` headers say where and how soon to poll. Once `state` is
        `completed` or `failed`, `items` lists every requested item in request
        order and the poll headers are gone.
      operationId: get-bulk-calculate-batch
      parameters:
        - name: Authorization
          in: header
          required: true
          example: Bearer YOUR_KEY_HERE
          schema:
            type: string
          description: >-
            The `Authorization` header is used to authenticate with the API
            using your API key. Value is of the format `Bearer YOUR_KEY_HERE`.
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Project UUID
        - name: batchId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The `batchId` returned when the batch was accepted.
      responses:
        '200':
          description: >-
            The batch's current status; `items` is present only once the batch
            is terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatus'
          headers:
            Location:
              description: >-
                Where to poll for the batch's status. Present while the batch is
                still running.
              schema:
                type: string
            Retry-After:
              description: >-
                Seconds to wait before polling again. Present while the batch is
                still running.
              schema:
                type: integer
        '400':
          description: The `projectId` or `batchId` path parameter is not a valid UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                invalid_uuid:
                  summary: batchId is not a UUID
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: batchId must be a UUID.
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                unauthorized:
                  summary: Missing or invalid API key
                  value:
                    type: https://httpproblems.com/http-status/401
                    title: Unauthorized
                    status: 401
                    detail: No Authorization Header
                    instance: >-
                      /v1/projects/56b9335c-6859-4978-a6ec-33d780599c23/batches/5ab97d3e-0030-4eaa-8c40-99057f2051f6
                    trace:
                      timestamp: '2026-09-23T04:45:10.007Z'
                      requestId: f03cb61f-756f-4d57-9092-7cabec5b9831
                      buildId: 61df8eb1-785b-4400-b31c-18f30edb3f5e
                      rayId: a3f6e5f97908f0dd
        '404':
          description: The batch does not exist, or is not accessible with this API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: Batch does not exist, or is not accessible with this API key
                  value:
                    error:
                      code: NOT_FOUND
                      message: batch not found
      security:
        - api_key: []
components:
  schemas:
    BatchStatus:
      type: object
      description: >-
        A bulk-calculate batch. The same body is returned when the batch is
        accepted and on every poll; `items` is `null` until `state` is terminal.
        Clients must tolerate `state` values not listed here.
      required:
        - batchId
        - type
        - state
        - progressPercent
        - projectId
        - itemCount
        - summary
        - createdAt
        - completedAt
        - durationSeconds
        - error
        - items
      properties:
        batchId:
          type: string
          format: uuid
          description: Identifier to poll.
        type:
          type: string
          description: Always `bulk-calculate`.
        state:
          type: string
          description: >-
            `processing` while sheets are being created and solved. `completed`
            once every item has an outcome; items that could not be solved carry
            their own `error`, so a completed batch can have `summary.solved` of
            0. `failed` when the batch itself could not run, or when it stopped
            before finishing and will not resume (see `error`). Treat an
            unrecognised value as still in progress.
        progressPercent:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            Whole-number share of the batch's own sheets solved so far, 0 to
            100, while `processing`. Set to 100 when the batch reaches
            `completed`, whatever `summary.solved` is; read `summary` for the
            outcome. Frozen where it stopped when `failed`.
        projectId:
          type: string
          format: uuid
        itemCount:
          type: integer
          description: Number of items requested.
        summary:
          type: object
          required:
            - total
            - solved
            - errored
            - stale
            - checkErrored
            - pending
          description: >-
            Counts over the items. `pending` is `total - solved - errored -
            stale` and is 0 once the batch is terminal, where every item is
            solved or carries an `error`. The three non-solved counters answer
            different questions and are never folded together, because the
            remedy differs: `errored` counts items the batch could not produce
            results for, where retrying is the fix; `stale` counts items it did
            solve whose inputs have changed since, where nothing failed and
            re-solving the sheet is the fix; `checkErrored` counts items that
            solved but whose governing check produced no verdict, and those are
            also counted in `solved`. To confirm every item is usable, check
            `errored`, `stale` and `checkErrored` are all 0. `state` is the
            completion signal. While `processing` the counts are progress, and
            `pending` can read 0 in the moments between the last sheet solving
            and the batch reaching a terminal state; do not use it to detect
            completion. On a terminal batch the counters are recomputed from the
            sheets' current state on every poll, so the same `batchId` can
            report different counts later if its sheets are edited or deleted.
          properties:
            total:
              type: integer
            solved:
              type: integer
            errored:
              type: integer
              description: >-
                Items the batch could not produce results for: the solver
                refused the sheet, the sheet is gone, or the batch stopped
                before reaching it. Retrying is the remedy.
            stale:
              type: integer
              description: >-
                Items the batch solved whose inputs have changed since, so the
                stored results no longer describe them. Not a failure — usually
                the caller edited the sheet themselves — and counted separately
                from `errored` so their own edit is not reported back as a batch
                failure. Re-solve the sheet, or resubmit the item.
            checkErrored:
              type: integer
              description: >-
                Items that solved but whose governing check produced no verdict:
                the items whose `summaryCheckStatus` is `error`. Counted
                separately from `errored`, and never folded into it: these items
                have current results, they just have no verdict to read.
            pending:
              type: integer
        createdAt:
          type: string
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: '`null` until the batch is terminal.'
        durationSeconds:
          type:
            - number
            - 'null'
          description: >-
            How long the batch took. Set when the batch reached a terminal state
            and the duration was recorded; `null` otherwise. A batch the worker
            had to mark failed as a last resort can be `failed` with
            `durationSeconds` null.
        error:
          oneOf:
            - $ref: '#/components/schemas/BatchError'
            - type: 'null'
          description: >-
            Why the batch itself failed. Set when the batch failed and the
            reason was recorded; `null` otherwise. A batch the worker had to
            mark failed as a last resort can be `failed` with `error` null.
        items:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BatchItem'
          description: >-
            One entry per requested item, in request order. `null` until the
            batch is terminal.
    ValidationError:
      type: object
      description: Validation error response for invalid API inputs
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
              description: Error code for validation failures
            message:
              type: string
              description: Human-readable error summary
              example: Input validation failed
            details:
              type: array
              description: Array of specific validation errors
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Path to the invalid field (e.g., 'L_X', 'supports.0.2')
                  message:
                    type: string
                    description: Description of what's wrong with the field
                required:
                  - field
                  - message
          required:
            - code
            - message
      required:
        - error
      example:
        error:
          code: VALIDATION_ERROR
          message: Input validation failed
          details:
            - field: L_X
              message: Expected number, received string
            - field: supports
              message: At least 2 supports are required
    ProblemDetails:
      type: object
      description: >-
        RFC 7807 (`application/problem+json`) error returned by the API gateway
        before a request reaches the handler — currently authentication failures
        (401). Note this differs from the `{ error: { code, message, details }
        }` envelope returned by the handler for validation and not-found errors.
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the problem type.
        title:
          type: string
          description: Short, human-readable summary of the problem type.
        status:
          type: integer
          description: HTTP status code.
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          description: The request path that produced the error.
        trace:
          type: object
          description: >-
            Gateway trace metadata for support (timestamp, requestId, buildId,
            rayId).
      required:
        - type
        - title
        - status
        - detail
    ErrorResponse:
      type: object
      description: >-
        Standard error envelope for handler errors. `code` is a stable
        machine-readable error code (e.g. NOT_FOUND, UPSTREAM_ERROR); `message`
        is human-readable and may change.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
          required:
            - code
            - message
      required:
        - error
    BatchError:
      type: object
      required:
        - code
        - message
      description: >-
        A batch-level failure. `code` is `VALIDATION_CHANGED` when a template
        became unavailable between acceptance and processing, `BATCH_FAILED`
        when the batch could not be run, or `BATCH_ABANDONED` when it stopped
        before finishing and will not resume — resubmit its items. Treat an
        unrecognised code as a failure to retry.
      properties:
        code:
          type: string
        message:
          type: string
    BatchItem:
      type: object
      description: >-
        One requested item's outcome: the sheet as `GET /v1/sheets/{sheetId}`
        returns it, plus `ref`, and `error` when it has no results. `inputs` is
        absent both when the sheet was never created (`sheetId` is `null`) and
        when its template is no longer accessible. `sheetUrl` is absent only
        when the sheet was never created.
      required:
        - ref
        - sheetId
        - projectId
        - templateCode
        - status
      properties:
        ref:
          type:
            - string
            - 'null'
          description: The `ref` sent for this item, or `null` if none was.
        sheetId:
          type:
            - string
            - 'null'
          format: uuid
          description: '`null` when no sheet was created for this item.'
        projectId:
          type: string
          format: uuid
        templateCode:
          type: string
        status:
          type: string
          enum:
            - solved
            - unsolved
          description: >-
            `solved` when `results` were computed from the inputs the sheet
            holds now. Any item that is not `solved` carries `error`.
        inputs:
          type: object
          additionalProperties: true
          description: As on `GET /v1/sheets/{sheetId}`.
        sheetUrl:
          type: string
          format: uri
          description: Link to the sheet in the Calcs.com app.
        passed:
          type:
            - boolean
            - 'null'
          deprecated: true
          description: >-
            Deprecated: read `summaryCheckStatus` for the verdict. `passed` is
            not this batch's verdict: a failing calculation can report `true`,
            even on its first solve, or `null`. Present when solved.
        results:
          type: object
          additionalProperties: true
          description: As on `GET /v1/sheets/{sheetId}`. Present when solved.
        summaryCheck:
          type:
            - number
            - boolean
          description: >-
            Value of the template's governing check for the last solve. Absent
            when the check could not be evaluated (`summaryCheckStatus` is
            `error`). A template that defines no governing check reports `true`
            here, so read the verdict from `summaryCheckStatus`, which tells the
            two apart (`not_evaluated`).
        summaryCheckReferenceId:
          type: string
          description: Reference ID of the widget `summaryCheck` came from.
        summaryCheckError:
          type: boolean
          description: >-
            Whether the governing check could not be evaluated. A check in error
            has no verdict and carries no `summaryCheck`; the item is still
            reported as solved, and `summary.checkErrored` counts it.
        summaryCheckFailReasons:
          type: array
          items:
            type: string
          description: >-
            Why the governing check failed. Present only when the check
            evaluated and failed; absent when it passed and when it errored.
        summaryCheckStatus:
          type: string
          enum:
            - pass
            - fail
            - error
            - not_evaluated
          description: >-
            Verdict of the template's governing check for the last solve.
            `pass`: the check passed (`summaryCheck` is `true`, or a number from
            0 to 1). `fail`: the check evaluated and failed (`false`, or a
            number outside 0 to 1). `error`: the check could not be evaluated —
            `summaryCheckError` is `true`, or the solve produced no value for a
            check the template defines; treat it as not passing.
            `not_evaluated`: the template defines no governing check. Present
            when solved.
        warnings:
          type: array
          description: >-
            Non-fatal findings against the attributes sent for this item, as a
            single calculate reports them. Absent when there is nothing to
            report, and withheld on an item whose template is no longer
            accessible.
          items:
            type: object
            properties:
              field:
                type: string
                description: The attribute key that was not applied.
              message:
                type: string
                description: What was wrong with it.
              type:
                type: string
                description: >-
                  Machine-readable reason: `unknown_field` for a key matching no
                  widget on the template, `null_value` for an explicit `null`
                  (skipped, not treated as a clear).
        error:
          $ref: '#/components/schemas/BatchItemError'
    BatchItemError:
      type: object
      required:
        - code
        - message
      description: >-
        Why one item has no results. `SOLVE_FAILED`: the solver could not answer
        this sheet. `RESULTS_STALE`: the batch solved this sheet, but its inputs
        have changed since (edited in the app, patched through the API, the
        project's defaults changed, or the sheet was upgraded), so the results
        no longer match. Solve the sheet again or resubmit the item.
        `SHEET_UNAVAILABLE`: the item has no sheet to report, either because it
        was deleted after the batch ran or because the batch died before
        creating it without recording a reason. `TEMPLATE_NOT_FOUND`: the
        template is no longer accessible with this API key. A batch-level code
        (`BATCH_FAILED`, `VALIDATION_CHANGED`, `BATCH_ABANDONED`) appears here
        when the batch stopped before this item was finished. Treat an
        unrecognised code as a failure.
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send your API key as a bearer token: `Authorization: Bearer
        YOUR_API_KEY`. Every endpoint requires one.
    api_key:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.