Skip to main content
Search does not use credits.
The TinyFish Search API lets you run web searches and get back structured results — titles, snippets, and URLs — ready for LLM consumption or programmatic use. 
GET https://api.search.tinyfish.ai
api.search.tinyfish.ai is the public Search API endpoint.

​
Before You Start

1

Get your API key

Visit agent.tinyfish.ai/api-keys and create a key. Store it in your environment:
export TINYFISH_API_KEY="your_api_key_here"
All requests require the X-API-Key header. See Authentication for the full setup and troubleshooting guide.

​
Your First Request

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(query="web automation tools")
for r in response.results:
    print(r.title, "→", r.url)

​
What Success Looks Like

{
  "query": "web automation tools",
  "results": [
    {
      "position": 1,
      "site_name": "tinyfish.ai",
      "title": "TinyFish — AI Web Automation Platform",
      "snippet": "Automate any website with natural language instructions...",
      "url": "https://tinyfish.ai"
    },
    {
      "position": 2,
      "site_name": "github.com",
      "title": "Top Web Automation Tools in 2026",
      "snippet": "A curated list of browser automation frameworks...",
      "url": "https://github.com/example/web-automation-tools"
    }
  ],
  "total_results": 10,
  "page": 0
}

​
When to Use Search vs the Other APIs

  • Use Search when you need ranked search engine results, snippets, and URLs.
  • Use Fetch when you already have the URLs and want extracted page content.
  • Use Agent when you want TinyFish to browse and execute a workflow on the site.
  • Use Browser when you need direct browser control from your own code.

​
Geo-Targeted Results

Use the location and language parameters to get results tailored to a specific region.

​
Freshness and Date Filters

Use recency_minutes when you want a freshness window, or after_date / before_date when you want a calendar date cutoff.
  • recency_minutes accepts an integer from 1 to 5256000 (10 years).
  • after_date and before_date must use YYYY-MM-DD.
  • Do not combine recency_minutes with after_date or before_date.
  • If you send both after_date and before_date, after_date must be less than or equal to before_date.

​
Domain Types

Use domain_type to search a specific content category:
  • web (default) — standard web results
  • news — news articles with publisher and date fields
  • research_paper — academic papers with authors, venue, year, and citation count
Date and recency filters (after_date, before_date, recency_minutes) are not supported for domain_type=research_paper.

​
Search Intent

The optional purpose parameter lets you state why you are searching — the underlying goal or task the results will be used for. A query is often a terse set of keywords, and the intent behind it isn’t always obvious from the keywords alone. Passing purpose gives us additional signal to further inform and deliver better-quality results.
  • purpose is always optional. Omitting it leaves search behaviour unchanged.
  • Keep it to a short phrase or sentence (maximum 2000 characters), for example Find an open-source library for parsing PDF invoices in Python.

API Reference

Full request and response schema

Authentication

API key setup

For coding agents

One page that routes an agent to the right TinyFish API

Search Examples

Common Search request patterns