Before You Start
1
Get your API key
Create an API key at agent.tinyfish.ai/api-keys.
2
Store it in your environment
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
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
npm install @tiny-fish/sdk, 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:
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
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
MCP dataset tools
Build and read datasets from Claude, Cursor, and other MCP clients
CLI dataset commands
Create, watch, and page through datasets from your terminal