Datasets API

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.

POST https://agent.tinyfish.ai/v1/datasets

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

Before You Start

Get your API key

Create an API key at agent.tinyfish.ai/api-keys.

Store it in your environment

export TINYFISH_API_KEY="your_api_key_here"

All requests require the X-API-Key header. See Authentication for setup and troubleshooting. To try TinySet without code, open the Datasets playground and follow Build your first dataset.

Your First Request

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)

tinyfish dataset create "Specialty coffee shops in Oakland with their website and rating" --rows 25 --pretty

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, 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:

{
  "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.

Build your first dataset

A step-by-step guide in the playground, then the same flow from code

Datasets reference

Endpoints, the spec format, statuses, events, errors, and limits

Start Here

Agent API

Search API

Monitor

Fetch API

Browser API

Research API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Datasets API

Before You Start

Your First Request

What Success Looks Like

When to Use Datasets vs the Other APIs

Read Next

Build your first dataset

Datasets reference

​Before You Start

​Your First Request

​What Success Looks Like

​When to Use Datasets vs the Other APIs

​Read Next

Build your first dataset

Datasets reference

Before You Start

Your First Request

What Success Looks Like

When to Use Datasets vs the Other APIs

Read Next