List or read grids

List the grids in a project, look at one grid’s setup or its processing status, or see the column types you can add to a grid.

Example: “What grids do I have going in this project?”

Usage: choose what you want with view — the grid inventory (list), one grid’s full setup (detail, needs the grid id), its processing status (status, needs the grid id), or the catalog of column types you can add (column_options). The inventory comes back in pages of up to 100 (50 by default) and can be narrowed by name, workflow, or who created it, and ranked by newest, most recently updated, or by how many rows sit in a given state (for example to surface the grids with the most failed rows first).

Response: for the inventory, a page of grids, each with its name, when it was created, its row and column counts, and how many rows sit in each processing state. Detail adds the grid’s columns and its saved sort and filter; status returns the counts plus who is editing it right now. Column options lists each addable type with its name and description.

POST /api/v1/business/grids/query

List or read grids

cURL

curl --request POST \
  --url https://api.example.com/api/v1/business/grids/query \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "grid_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workflow_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "page": 1,
  "page_size": 50,
  "sort_by": "created_at",
  "sort_order": "desc",
  "sort_status": "awaiting_interaction",
  "search": "<string>",
  "created_by": [
    "<string>"
  ],
  "last_run_after": "2023-11-07T05:31:56Z",
  "last_run_before": "2023-11-07T05:31:56Z"
}
'

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

Grid listing: 'list' (inventory), 'detail' (config), 'status' (processing), or 'column_options' (the live, project-specific catalog of addable column types and usable workflow columns — call it to get the valid column types rather than guessing them).

Available options: list, detail, status, column_options

grid_id · string<uuid> | null

Grid id. Required for view='detail' and view='status'. Optional for view='list' and view='column_options'

workflow_ids · string<uuid>[] | null

Optional workflow filter for the list view

page · integer · default: 1

Required range: x >= 1

page_size · integer · default: 50

Required range: 1 <= x <= 100

sort_by · enum<string> · default: created_at

Sort the list view by created_at, updated_at, or status_count. Use status_count to rank grids by how many rows are in the sort_status state — e.g. sort_by=status_count + sort_status=failed + sort_order=desc surfaces the grids with the most failed rows first, so 'which grids failed' is answered from the top of one page instead of scanning every grid.

Available options: created_at, updated_at, status_count

sort_order · enum<string> · default: desc

Sort direction for sort_by; asc or desc.

Available options: asc, desc

sort_status · enum<string> · default: awaiting_interaction

Row status counted when sort_by=status_count (e.g. failed, completed, awaiting_interaction). Pairs with sort_by=status_count to rank grids by that status.

Available options: pending, running, completed, failed, cancelled, awaiting_interaction

search · string | null

Free-text filter on grid name for the list view.

created_by · string[] | null

Filter by creator user id(s)

last_run_after · string<date-time> | null

Only grids with a run at/after this time

last_run_before · string<date-time> | null

Only grids with a run at/before this time

Response

200

application/json

Successful Response