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

# List grids

> List the grids in your account, including a column-schema summary and row count per grid.

Returns the grids visible to your API key, with enough metadata to discover grid IDs before exporting their rows via [Get grid rows](/api-reference/grids/get-rows).

## Authentication

Bearer token. See [Authentication](/api-reference/authentication).

## Query parameters

| Name            | Type                   | Required | Description                                               |
| :-------------- | :--------------------- | :------- | :-------------------------------------------------------- |
| `limit`         | integer                | No       | Page size, default `50`, max `200`.                       |
| `cursor`        | string                 | No       | Opaque pagination cursor returned by a previous response. |
| `name`          | string                 | No       | Case-insensitive substring match against grid name.       |
| `updated_after` | string (ISO-8601, UTC) | No       | Only return grids updated at or after this timestamp.     |

## Response

```json theme={null}
{
  "data": [
    {
      "grid_id": "grd_01HX2K8E4Y",
      "name": "Dairy Q2 review",
      "row_count": 1284,
      "created_at": "2026-04-12T08:42:11Z",
      "updated_at": "2026-05-21T19:00:55Z",
      "created_by": {
        "user_id": "usr_01J7",
        "email": "pricing@yourcompany.com"
      },
      "columns": [
        { "name": "product_id", "type": "string", "source": "canonical" },
        { "name": "price", "type": "number", "source": "canonical" },
        { "name": "margin", "type": "number", "source": "formula" },
        { "name": "role", "type": "single_select", "source": "custom" }
      ]
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}
```

The `columns` array is a summary - column names, semantic type, and where each column came from (`canonical`, `custom`, `formula`, `ai`). It does **not** include row values. To pull row values, call [Get grid rows](/api-reference/grids/get-rows) with the `grid_id`.

## Example request

```bash theme={null}
curl -s "https://clientapi.retailgrid.io/v1/grids?limit=25&updated_after=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer rg_live_xxx"
```

## Related

* [Get grid rows](/api-reference/grids/get-rows)
* [Conventions](/api-reference/conventions)
* [Errors](/api-reference/errors)