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

# Datasets API

> Describe a dataset in one sentence and TinySet fills it from the web

TinySet builds a structured dataset from a plain-English description. It designs the columns, searches the web for
matching entities, and fills one row per entity with values it found on real pages. Use it when you know the shape of the
data you want, such as a list of companies, venues, or products with the same fields for each, and need it filled.

```bash theme={null}
POST https://agent.tinyfish.ai/v1/datasets
```

> [!NOTE]
>
> Datasets is in beta. Runs are free during the beta, and each account can start 3 runs per rolling 24 hours.

## Before You Start

**1. Get your API key**

Create an API key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).

**2. Store it in your environment**

```bash theme={null}
export TINYFISH_API_KEY="your_api_key_here"
```

All requests require the `X-API-Key` header. See [Authentication](https://docs.tinyfish.ai/authentication.md) for setup and troubleshooting.
To try TinySet without code, open the [Datasets playground](https://agent.tinyfish.ai/playground/datasets) and follow
[Build your first dataset](https://docs.tinyfish.ai/datasets/guide.md).

## Your First Request

```python Python theme={null}
from tinyfish import TinyFish

client = TinyFish()
dataset = client.datasets.create(
    prompt="Specialty coffee shops in Oakland with their website and rating",
    target_rows=25,
)

with client.datasets.events(dataset.id, dataset.run.id) as events:
    for event in events:
        if event.event == "status":
            print(event.status)

page = client.datasets.rows(dataset.id)
for row in page.rows:
    print(row.data)
```

```bash CLI theme={null}
tinyfish dataset create "Specialty coffee shops in Oakland with their website and rating" --rows 25 --pretty
```

```bash cURL theme={null}
curl https://agent.tinyfish.ai/v1/datasets \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Specialty coffee shops in Oakland with their website and rating",
    "target_rows": 25
  }'
```

`create` plans the columns from your prompt, which can take up to a minute, then starts filling the dataset and
returns `202` without waiting for rows. A run usually takes 5 to 20 minutes. Follow it with the run's
[event stream](https://docs.tinyfish.ai/datasets/reference.md#event-stream), or check `GET /v1/datasets/{id}` until `status` is `ready`, `failed`,
or `cancelled`, then read the rows. Install the SDK with `pip install tinyfish` or the
CLI with `npm install -g @tiny-fish/cli`.

## What Success Looks Like

`POST /v1/datasets` returns the dataset with its planned columns and the run that is filling it:

```json theme={null}
{
  "id": "1b6c...",
  "name": "Oakland Specialty Coffee Shops",
  "spec": {
    "name": "Oakland Specialty Coffee Shops",
    "description": "Specialty coffee shops located in Oakland, California",
    "columns": [
      { "name": "shop_name", "label": "Shop Name", "type": "string", "is_primary_key": true },
      { "name": "website", "label": "Website", "type": "url", "is_primary_key": false },
      { "name": "rating", "label": "Rating", "type": "number", "is_primary_key": false }
    ]
  },
  "status": "populating",
  "target_rows": 25,
  "row_count": 0,
  "run": { "id": "7f2a...", "status": "queued", "started_at": "2026-10-28T21:30:00Z" },
  "created_at": "2026-10-28T21:30:00Z"
}
```

When the run ends, `status` is `ready` and `GET /v1/datasets/{id}/rows` returns one object per row, with cells keyed
by column `name`.

## When to Use Datasets vs the Other APIs

* Use **Datasets** when you know the columns you want and need many rows filled with the same fields.
* Use **Research** when you don't know what you'll find and want a cited report.
* Use **Search** for ranked links and snippets.
* Use **Fetch** when you already know which pages to extract.
* Use **Agent** when TinyFish should interact with websites.

## Read Next

> **[Build your first dataset](https://docs.tinyfish.ai/datasets/guide.md)**
>
> A step-by-step guide in the playground, then the same flow from code

> **[Datasets reference](https://docs.tinyfish.ai/datasets/reference.md)**
>
> Endpoints, the spec format, statuses, events, errors, and limits


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.