Read grid data

Read what is inside a grid: its columns, its rows, a single cell, the run behind a computed cell, or the rows matching a search.

Example: “Show me the columns of the ‘FAQ Suggester v2 Grid’ grid”

Usage: pick what to read with view and always pass the grid id. columns lists the grid’s columns; rows returns the data a page at a time (up to 200, 50 by default) and can be limited to certain columns or specific rows; cell and cell_run open one cell (both need the row id and column id, and cell_run also needs the run id); row_search finds rows matching your text (needs the search text).

Response: columns come back with their names and types; rows come as a page of cell values tagged with the grid version; a cell returns its value, status, and the run that produced it; a cell run returns its inputs, status, and version; a search returns the row-and-column matches.

POST /api/v1/business/grids/data

Read grid data

cURL

curl --request POST \
  --url https://api.example.com/api/v1/business/grids/data \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "grid_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "row_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "column_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "query": "<string>",
  "page": 1,
  "page_size": 50,
  "column_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "row_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "column_type": [],
  "field_name": "<string>",
  "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Headers

x-project-id · string<uuid> · required

Project ID for tenant scoping

X-Workspace-Id · string<uuid> | null

Overrides the key's workspace

X-API-Key · string | null

User API key

Body

application/json

view · enum<string> · required

Which grid data slice to return: columns, rows, cell (needs row_id/column_id), cell_run (that cell's producing run - needs row_id/column_id/workflow_run_id), or row_search. Prefer cell/cell_run over rows+page_size=1 for a single-row/cell question - but only for expandable (blob-backed) columns, e.g. workflow/output columns with markdown/json/array/file content; plain scalar columns (text/number/boolean/single_select) already return their full value via rows and have no cell view to expand.

Available options: columns, rows, cell, cell_run, row_search

grid_id · string<uuid> · required

Grid to read from

row_id · string<uuid> | null

Row id; required for cell and cell_run views

column_id · string<uuid> | null

Column id; required for cell and cell_run views. For cell_run specifically, must be the WORKFLOW-type column id (not the input/output column) - the one whose AI runs are being traced.

workflow_run_id · string<uuid> | null

Run id; required for the cell_run view

query · string | null

Search text; required for the row_search view. row_search matches only searchable (text-like input) cell values — generated workflow output stored as markdown/JSON/blobs is not indexed and won't match.

page · integer · default: 1

Required range: x >= 1

page_size · integer · default: 50

Required range: 1 <= x <= 200

column_ids · string<uuid>[] | null

Column id filter for the rows view — return only these columns per row instead of every column. See also field_name/column_type for the columns view.

row_ids · string<uuid>[] | null

Row id filter for the rows view — fetch specific, non-contiguous rows (e.g. 'rows 3, 7, and 9') instead of a page range. Resolve ordinal positions to ids with a prior rows view read, then pass them here.

column_type · enum<string>[] | null

Column-type filter for the columns view. Defaults to INPUT columns; pass ['output'] to see the generated/workflow columns the grid produces for each row.

Available options: input, workflow, output

field_name · string | null

Column filter for the columns view — matches the underlying workflow input schema's field name (not the grid's display column name). Use this to answer 'which column maps to field X' directly instead of listing all columns and matching by eye.

workflow_id · string<uuid> | null

Filter columns by workflow id (for the columns view)

Response

200

application/json

Successful Response