> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/mcp-server/tools-and-support/tools/grids.md).

# Grids

Read and write Grid data, configure columns, and run rows.

Read and write Grid data, configure columns, and run rows.

See [plan access](broken://pages/GlhqboJgu5fTfPseY3y1#plan-access) and [query options](broken://pages/GlhqboJgu5fTfPseY3y1#query-options) for shared requirements.

Tools for reading, writing, creating, and executing AirOps Grids programmatically. Use these to populate data, manage columns, trigger workflow runs, and retrieve results.

## `create_grid`

Create a new empty, general-purpose Grid with one empty sheet. Use `add_grid_column` to add columns and `write_grid` to add rows.

**Requires:** `name`

**Optional fields:** `workspace_id`

***

## `create_grid_sheet`

Create a new sheet within an existing Grid.

**Requires:** `grid_id`, `name`

***

## `list_grids`

List grids the authenticated user has access to. Use `includes: ["grid_tables.grid_columns"]` to get the table and column structure needed for other grid tools.

**Returns:** Grid ID, name, owning workspace, relationship context, and optionally table and column details (ID, title, data type, position).

Results include standalone Grids and Campaign Action Grids. Check `grid_type` (`standalone` or `campaign_action`), `campaign_id`, `campaign_name`, `campaign_status`, `brand_kit_id`, and `brand_kit_name` to identify their context. Template origin is available through `campaign_origin_template_id`, `campaign_origin_template_name`, and `grid_origin_template_id`.

Workspace and relationship fields remain present even when `fields` selects only `id` and `name`. Relationship details are `null` when absent or inaccessible. Grid names can come from templates, so use the explicit relationships to identify the brand.

| Parameter    | Values                         |
| ------------ | ------------------------------ |
| **Filters**  | name, workspace\_id            |
| **Sort**     | name, updated\_at, created\_at |
| **Includes** | grid\_tables.grid\_columns     |

***

## `read_grid`

Read rows from a grid table. Returns rows as objects with column titles as keys.

**Requires:** `grid_id`, `grid_table_id`

**Returns:** Grid metadata, columns (with writable flag), and row data with pagination info. The response includes the same workspace, Campaign, Brand Kit, and template context as `list_grids`, including for empty sheets.

Playbook columns also include `playbook_id` and `artifacts`, with each Artifact's `name` and `artifact_type`. Use these names when mapping a Playbook column's output into another execution column.

| Parameter             | Type    | Default | Description                                                     |
| --------------------- | ------- | ------- | --------------------------------------------------------------- |
| `filters`             | array   | none    | Filter by column values                                         |
| `filters[].column_id` | integer | none    | Column ID to filter on                                          |
| `filters[].operator`  | string  | none    | CONTAINS, NOT\_CONTAINS, EMPTY, NOT\_EMPTY, =, !=, >=, <=, >, < |
| `filters[].value`     | string  | none    | Filter value (not required for EMPTY/NOT\_EMPTY)                |
| `column_ids`          | array   | all     | Column IDs to include in results                                |
| `limit`               | integer | 50      | Rows per page (1–100)                                           |
| `offset`              | integer | 0       | Row offset for pagination                                       |
| `truncate`            | integer | 0       | Max characters per cell (0 = no truncation)                     |

Use `list_grids` to find the Grid and sheet IDs before reading. Filters must reference columns in that sheet and use operators supported by each column type. Invalid columns, numeric values, or operators reject the whole request rather than returning partially filtered rows. `EMPTY` and `NOT_EMPTY` do not require a value.

***

## `read_grid_cell`

Read the full value of a single Grid cell. Use this when `read_grid` truncates a long cell, such as a full article, brief, JSON payload, or HTML field.

**Requires:** `grid_id`, `grid_table_id`, `row_id`, `column_id`

**Returns:** Column title, full value, and value type.

***

## `write_grid`

Create or update rows in a grid table. Maximum 1000 rows per call.

**Requires:** `grid_id`, `grid_table_id`, `mode`, `rows`

| Parameter | Type   | Description                                                                               |
| --------- | ------ | ----------------------------------------------------------------------------------------- |
| `mode`    | string | `create` to add new rows, `update` to modify existing rows                                |
| `rows`    | array  | Row objects with column titles as keys. For `update` mode, include `__id` with the row ID |

**Returns:** `rows_created` (create mode) or `rows_updated` and `cells_updated` (update mode).

{% hint style="info" %}
Values can be strings, numbers, booleans, arrays, or objects. Arrays and objects are stored as JSON. Column titles must exactly match existing grid columns. Use `add_grid_column` to create new columns first.
{% endhint %}

***

## `run_grid_rows`

Trigger execution of one or more grid rows. This runs all workflow (app execution) columns for each specified row, in dependency order. Execution is asynchronous. this tool returns immediately with execution metadata.

**Requires:** `grid_id`, `grid_table_id`, `grid_row_ids`

| Parameter      | Type  | Description                              |
| -------------- | ----- | ---------------------------------------- |
| `grid_row_ids` | array | IDs of the grid rows to execute (max 50) |

**Returns:** Execution metadata, including the row execution IDs to poll with `get_grid_row_execution_status`.

{% hint style="info" %}
Maximum 50 rows per call. Use `get_grid_row_execution_status` to check progress and completion.
{% endhint %}

***

## `get_grid_row_execution_status`

Check the status of grid row executions. Use this after `run_grid_rows` to poll for completion.

**Requires:** `grid_id`, `row_execution_ids`

| Parameter           | Type  | Description                                 |
| ------------------- | ----- | ------------------------------------------- |
| `row_execution_ids` | array | IDs of the row executions to check (max 50) |

**Returns:** Overall status and per-column detail for each execution.

***

## `add_grid_column`

Add a new column to a grid table. Use this before `write_grid` when you need to write to a column that doesn't exist yet.

**Requires:** `grid_id`, `grid_table_id`, `title`, `data_type`

| Parameter   | Type    | Description                                                                                                   |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `title`     | string  | Column title                                                                                                  |
| `data_type` | string  | text, number, datetime, markdown, url, html, image\_from\_url, json, single\_select, playbook, app\_execution |
| `position`  | integer | Optional column position (appended at end if omitted)                                                         |

**Returns:** Created column's ID, title, data type, and position.

For a Playbook column, use `data_type: "playbook"` and provide `playbook_id`. For a Workflow column, use `data_type: "app_execution"` and provide `workflow_id`. Configure `inputs` by Input name. Each mapping requires `type` and `value`.

When mapping from a Playbook column, `value` is the source column ID in the same sheet, and `artifact_name` is the exact Artifact name:

```json
{
  "article": {
    "type": "column",
    "value": 123,
    "artifact_name": "Final Article"
  }
}
```

This example is an `inputs` object. Copy the Artifact name from `read_grid`, or from the `artifacts` metadata returned when `add_grid_column` creates the source Playbook column.

***

## `update_grid_column`

Update a Grid column's title, data type, or Playbook/Workflow Input mappings.

**Requires:** `grid_id`, `grid_table_id`, `grid_column_id`, and at least one of `title`, `data_type`, or `inputs`

**Returns:** Grid and sheet IDs plus the updated column's ID, title, data type, and position. Playbook and Workflow columns also include their configuration details.

Passing `inputs` replaces the entire Input mapping. Include every Input you want to keep. The tool cannot reposition a column or change which Playbook or Workflow it runs.

***

## `delete_grid_column`

Delete a Grid column and its dependent Workflow output or Playbook Artifact columns.

**Requires:** `grid_id`, `grid_table_id`, `grid_column_id`

**Returns:** `grid_id`, `grid_table_id`, and `deleted_column_ids` for all affected columns.

{% hint style="warning" %}
Review dependent columns before deleting. Deletion is blocked while row executions are running for the sheet.
{% endhint %}

***

## Example: Grid Data Workflow

A typical programmatic workflow using Grid tools:

1. **Discover:** Call `list_grids` with includes to find the grid and its column structure
2. **Prepare:** Call `add_grid_column` to create any missing columns
3. **Populate:** Call `write_grid` with mode `create` to add rows
4. **Execute:** Call `run_grid_rows` to trigger the row's workflow columns, then poll `get_grid_row_execution_status` until complete
5. **Retrieve:** Call `read_grid` to pull the results
6. **Update:** Optionally call `write_grid` with mode `update` to write data back


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/mcp-server/tools-and-support/tools/grids.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.