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

# Get a grid execution

> Follow a grid execution's progress and see which rows and columns it covers.



## OpenAPI

````yaml api-reference/openapi.yaml GET /v1/grids/{grid_id}/sheets/{sheet_id}/executions/{execution_id}
openapi: 3.0.3
info:
  title: QX API
  version: '1.0'
  description: >-
    Run what you build in QX from your own code. Message agents, execute flows
    and grids, and read their results.
servers:
  - url: https://api.qxlabs.com
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: >-
      Message agents through OpenAI's Responses API, so OpenAI's SDKs work with
      a QX API key.
  - name: Flows
    description: Execute flows and follow their executions.
  - name: Grids
    description: Execute grids, follow their executions and read their rows.
paths:
  /v1/grids/{grid_id}/sheets/{sheet_id}/executions/{execution_id}:
    get:
      tags:
        - Grids
      summary: Get a grid execution
      description: >
        Returns an execution's status and progress.

        Poll it every few seconds until `status` is `completed`, `error` or
        `cancelled`, then read the results from the sheet endpoint, passing the
        execution's `row_ids` and `column_ids` to read only what it produced.
      operationId: getGridExecution
      parameters:
        - name: grid_id
          in: path
          required: true
          schema:
            type: string
          description: The grid's ID
          example: 3e7a9c415b2d4f8ea6c19d0b2e4f7a18
        - name: sheet_id
          in: path
          required: true
          schema:
            type: string
          description: The sheet's ID
          example: b2d4f6a81c3e4a5b8d7f0e9c2a4b6d81
        - name: execution_id
          in: path
          required: true
          schema:
            type: string
          description: The execution's ID, from the execute endpoint
          example: 5c8a2e4f-6b1d-4a3c-9e7f-2d4b6a8c0e13
      responses:
        '200':
          description: The execution
          content:
            application/json:
              schema:
                type: object
                properties:
                  execution_id:
                    type: string
                  grid_id:
                    type: string
                  sheet_id:
                    type: string
                  status:
                    type: string
                    enum:
                      - queued
                      - processing
                      - completed
                      - error
                      - cancelled
                  progress:
                    type: object
                    description: >-
                      Cell counts. A cell that failed shows its own error in the
                      sheet endpoint
                    properties:
                      total_cells:
                        type: integer
                      completed_cells:
                        type: integer
                      skipped_cells:
                        type: integer
                      failed_cells:
                        type: integer
                      cancelled_cells:
                        type: integer
                  error:
                    type: string
                    nullable: true
                    description: The error for the execution as a whole, if there is one
                  column_ids:
                    type: array
                    items:
                      type: string
                    description: The IDs of the columns the execution covers
                  row_ids:
                    type: array
                    items:
                      type: string
                    description: >-
                      The IDs of the rows the execution covers, up to the first
                      500
              example:
                execution_id: 5c8a2e4f-6b1d-4a3c-9e7f-2d4b6a8c0e13
                grid_id: 3e7a9c415b2d4f8ea6c19d0b2e4f7a18
                sheet_id: b2d4f6a81c3e4a5b8d7f0e9c2a4b6d81
                status: processing
                progress:
                  total_cells: 240
                  completed_cells: 150
                  skipped_cells: 6
                  failed_cells: 4
                  cancelled_cells: 0
                error: null
                column_ids:
                  - 9f8e7d6c5b4a439281706f5e4d3c2b1a
                row_ids:
                  - 7d1e3f5a9b2c4d6e8f0a1b3c5d7e9f20
                  - e4a6c8b02d1f4e3ab5c79d0e1f2a3b46
        '403':
          description: The grid is in your org but isn't shared with you
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: There's no such grid or sheet, or no such execution on that sheet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Execution run not found
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Read rate limit exceeded for grids endpoints
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >
            curl
            https://api.qxlabs.com/v1/grids/3e7a9c415b2d4f8ea6c19d0b2e4f7a18/sheets/b2d4f6a81c3e4a5b8d7f0e9c2a4b6d81/executions/5c8a2e4f-6b1d-4a3c-9e7f-2d4b6a8c0e13
            \
              -H "Authorization: Bearer <YOUR_QX_API_KEY>"
        - lang: python
          label: Python
          source: >
            import time


            import requests


            headers = {"Authorization": "Bearer <YOUR_QX_API_KEY>"}

            url =
            "https://api.qxlabs.com/v1/grids/3e7a9c415b2d4f8ea6c19d0b2e4f7a18/sheets/b2d4f6a81c3e4a5b8d7f0e9c2a4b6d81/executions/5c8a2e4f-6b1d-4a3c-9e7f-2d4b6a8c0e13"


            # Poll until the execution has finished

            while True:
                execution = requests.get(url, headers=headers).json()
                if execution["status"] in ("completed", "error", "cancelled"):
                    break
                time.sleep(3)
            print(execution["progress"], execution["row_ids"])
        - lang: typescript
          label: TypeScript
          source: >
            const headers = { Authorization: "Bearer <YOUR_QX_API_KEY>" };

            const url =
            "https://api.qxlabs.com/v1/grids/3e7a9c415b2d4f8ea6c19d0b2e4f7a18/sheets/b2d4f6a81c3e4a5b8d7f0e9c2a4b6d81/executions/5c8a2e4f-6b1d-4a3c-9e7f-2d4b6a8c0e13";


            // Poll until the execution has finished

            let execution;

            while (true) {
              execution = await (await fetch(url, { headers })).json();
              if (["completed", "error", "cancelled"].includes(execution.status)) break;
              await new Promise((resolve) => setTimeout(resolve, 3000));
            }

            console.log(execution.progress, execution.row_ids);
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your QX API key. The `X-API-Key` header works too

````

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