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

# AI Tables Basics

> Create a table, add rows, run agents, and read results.

## Overview

This guide walks through a repeatable company-table workflow: create a table, add rows, run enrichment, and read the results.
You can start with companies discovered in Extruct or with your own list of company domains or URLs.

## Prerequisites

```bash theme={null}
export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"
```

Generate tokens in [Dashboard API Tokens](https://app.extruct.ai/api-tokens). For full setup, see [Authentication](/api-reference/authentication).

## Endpoints used

* [Create table (`POST /v1/tables`)](/api-reference/tables/create-table)
* [Add rows (`POST /v1/tables/:table_id/rows`)](/api-reference/tables/create-table-rows)
* [Run table (`POST /v1/tables/:table_id/run`)](/api-reference/tables/run-table)
* [Get table (`GET /v1/tables/:table_id`)](/api-reference/tables/get-table)
* [Get table data (`GET /v1/tables/:table_id/data`)](/api-reference/tables/get-table-data)

## Workflow

### 1) Create a table

The create-table response includes `id`, which you will reuse as `TABLE_ID`.

```bash theme={null}
TABLE_RESPONSE=$(curl -sS -X POST "https://api.extruct.ai/v1/tables" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{
    "name": "Company Research",
    "kind": "company",
    "column_configs": [
      {
        "kind": "input",
        "name": "Company",
        "key": "input"
      },
      {
        "kind": "agent",
        "name": "Description",
        "key": "description",
        "value": {
          "agent_type": "research_pro",
          "prompt": "Describe what the company does in 2 short sentences.",
          "output_format": "text"
        }
      }
    ]
  }')

TABLE_ID=$(echo "${TABLE_RESPONSE}" | jq -r '.id')
echo "${TABLE_ID}"
```

Requires `jq`. If unavailable, copy `id` manually from response.

### 2) Add rows

These rows can come from Extruct search results, Deep Search output, or your own company list.
For `company` tables, the most reliable `input` value is the company's official website domain or URL.

```bash theme={null}
curl -X POST "https://api.extruct.ai/v1/tables/${TABLE_ID}/rows" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{
    "rows": [
      {"data": {"input": "https://extruct.ai"}},
      {"data": {"input": "https://openai.com"}}
    ],
    "run": false
  }'
```

After rows are added, Extruct can populate built-in company fields such as `company_profile`, `company_name`, and `company_website`.
Use [Column Guide](/api-guides/ai-tables/column-guide) for minimum working shapes, column-selection rules, and prompt guidance. Use [Column Library](/api-guides/ai-tables/column-library) when you want fuller reusable templates and common chains.

### 3) Run the table

```bash theme={null}
curl -X POST "https://api.extruct.ai/v1/tables/${TABLE_ID}/run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -d '{"mode": "new"}'
```

### 4) Check status

```bash theme={null}
curl --get "https://api.extruct.ai/v1/tables/${TABLE_ID}" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}"
```

Proceed when `run_status` is `idle` and `num_cells_in_progress` is `0`.

### 5) Read enriched rows

```bash theme={null}
curl --get "https://api.extruct.ai/v1/tables/${TABLE_ID}/data" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=50"
```

## Troubleshooting

### `401 Unauthorized`

The token is missing or invalid.
Check that `EXTRUCT_API_TOKEN` is set and the header is exactly `Authorization: Bearer ${EXTRUCT_API_TOKEN}`.

### `422 Unprocessable Entity`

The payload shape is invalid. Common issues:

* `rows` must be an array of row objects with `data`.
* `column_configs` entries must include required fields by column type.
* `run` must be boolean when provided.

Validate your payload JSON before sending: `echo '<json-body>' | jq empty`.