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

# tables list

> List tables in the workspace pinned to your API key.

List the tables available to the authenticated workspace. Each row carries a `queryEnabled` flag for whether the table is enabled for query sync — use [`clay tables update`](/cli/reference/tables-update) to toggle it, and [`clay tables query`](/cli/reference/tables-query) to run queries.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay tables list [--limit <n>] [--cursor <token>] [--query-enabled]
```

Results are paginated. `--limit` sets the page size, and the response includes a top-level `cursor` when more tables are available; pass it back with `--cursor` to fetch the next page.

## Flags

| Flag               | Description                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `--limit <n>`      | Maximum tables to return per page. Must be a positive integer up to 100. Defaults to 20. |
| `--cursor <token>` | Resume from a previous response's `cursor` to fetch the next page.                       |
| `--query-enabled`  | Only return tables enabled for query sync.                                               |

## Output

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "tbl_abc123",
      "name": "Leads",
      "description": "Inbound leads.",
      "workbook": { "id": "wb_xyz789", "name": "Growth" },
      "queryEnabled": true
    }
  ],
  "cursor": "next_page_token"
}
```

| Field                 | Type                   | Description                                                                                    |
| --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
| `data[].id`           | string                 | Table id.                                                                                      |
| `data[].name`         | string                 | Display name.                                                                                  |
| `data[].description`  | string \| null         | Description, or `null` if not set.                                                             |
| `data[].workbook`     | `{ id, name }` \| null | The workbook the table belongs to, or `null`.                                                  |
| `data[].queryEnabled` | boolean                | Whether the table is enabled for query sync.                                                   |
| `cursor`              | string                 | Present when more tables are available. Pass it back via `--cursor`. Omitted on the last page. |

## Errors

| Code               | Exit | Notes                                               |
| ------------------ | ---- | --------------------------------------------------- |
| `validation_error` | 2    | `--limit` is not a positive integer or exceeds 100. |
| `auth_forbidden`   | 3    | The API key lacks the `cli:all` scope.              |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay tables list
clay tables list --query-enabled | jq -r '.data[].id'
clay tables list --limit 50 --cursor "$CURSOR"
clay tables list --query-enabled | jq -r '.data[] | select(.queryEnabled) | .name'
```