> ## 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 get

> Get metadata for a table, including row count and archive linkage.

Fetch metadata for a single table: its row count, creation time, and archive linkage. The response shape is discriminated on `type` — a regular table links to its archive companion (if any), and an archive table points back to its parent. List tables with [`clay tables list`](/cli/reference/tables-list).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay tables get <tableId>
```

## Arguments

| Argument  | Description                             |
| --------- | --------------------------------------- |
| `tableId` | The id of the table to fetch. Required. |

## Output

A regular table:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "regular",
  "id": "tbl_123",
  "name": "Leads",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "rowCount": 1200,
  "archive": { "tableId": "tbl_archive", "searchableFieldFormula": null }
}
```

An archive table:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "archive",
  "id": "tbl_archive",
  "name": "Leads (archive)",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "rowCount": 50000,
  "parentTableId": "tbl_123"
}
```

| Field           | Type                                          | Description                                                             |
| --------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| `type`          | `"regular" \| "archive"`                      | Discriminates the two output shapes.                                    |
| `id`            | string                                        | Table id.                                                               |
| `name`          | string                                        | Display name.                                                           |
| `createdAt`     | string                                        | Creation timestamp.                                                     |
| `rowCount`      | number                                        | Number of rows in the table.                                            |
| `archive`       | `{ tableId, searchableFieldFormula }` \| null | Regular tables only. Links to the archive companion, or `null` if none. |
| `parentTableId` | string                                        | Archive tables only. Id of the regular table this archives.             |

## Errors

| Code               | Exit | Notes                                                                 |
| ------------------ | ---- | --------------------------------------------------------------------- |
| `validation_error` | 2    | The `tableId` argument is required.                                   |
| `not_found`        | 6    | No table with that id in the workspace.                               |
| `auth_forbidden`   | 3    | The API key lacks the `cli:all` scope, or you cannot read this table. |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay tables get tbl_123
clay tables get tbl_123 | jq -r '.rowCount'
clay tables get tbl_123 | jq -r 'if .type == "archive" then .parentTableId else .archive.tableId end'
```