Fetch API

POST https://api.fetch.tinyfish.ai

​

Before You Start

export TINYFISH_API_KEY="your_api_key_here"

​

Your First Request

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(urls=["https://www.tinyfish.ai/"])
print(result.results[0].title)
print(result.results[0].text)

import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: ["https://www.tinyfish.ai/"],
});
console.log(result.results[0].title);
console.log(result.results[0].text);

curl -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.tinyfish.ai/"]}'

​

What Success Looks Like

{
  "results": [
    {
      "url": "https://www.tinyfish.ai/",
      "final_url": "https://www.tinyfish.ai/",
      "title": "TinyFish | Enterprise Web Agent Infrastructure",
      "description": "TinyFish provides enterprise infrastructure for AI web agents.",
      "language": "en",
      "format": "markdown",
      "text": "# TinyFish | Enterprise Web Agent Infrastructure\n\nTinyFish provides enterprise infrastructure for AI web agents...\n"
    }
  ],
  "errors": []
}

​

When to Use Fetch vs the Other APIs

• Use Fetch when you already know the URL and need clean extracted page content.
• Use Search when you need help finding the right URLs first.
• Use Agent when TinyFish should perform a multi-step workflow on the site.
• Use Browser when you need direct browser control from your own code.

​

Fetching Multiple URLs

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=[
        "https://www.tinyfish.ai/",
        "https://en.wikipedia.org/wiki/Web_scraping",
        "https://docs.python.org/3/tutorial/index.html",
    ]
)

for page in result.results:
    print(page.url, "→", page.title)

for error in result.errors:
    print("Failed:", error.url, "–", error.error)

import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: [
    "https://www.tinyfish.ai/",
    "https://en.wikipedia.org/wiki/Web_scraping",
    "https://docs.python.org/3/tutorial/index.html",
  ],
});

result.results.forEach((r) => console.log(r.url, "→", r.title));
result.errors.forEach((e) => console.log("Failed:", e.url, "–", e.error));

curl -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tinyfish.ai/",
      "https://en.wikipedia.org/wiki/Web_scraping",
      "https://docs.python.org/3/tutorial/index.html"
    ]
  }'

​

Output Formats

{
  "format": "html",
  "text": "<h1>Async Fn in Traits Are Now Available</h1>
<p>Starting with Rust 1.75, you can use <code>async fn</code> directly inside traits.</p>
<h2>What Changed</h2>
<ul>
<li>Works in all stable traits</li>
<li>No heap allocation for simple cases</li>
</ul>"
}

{
  "format": "markdown",
  "text": "# Async Fn in Traits Are Now Available

Starting with Rust 1.75, you can use `async fn` directly inside traits.

## What Changed

Previously, writing async functions in traits required the `async-trait` crate...

- Works in all stable traits
- No heap allocation for simple cases
- Compatible with `Send` bounds"
}

{
  "format": "json",
  "text": {
    "type": "document",
    "children": [
      { "type": "heading", "level": 1, "text": "Async Fn in Traits Are Now Available" },
      { "type": "paragraph", "text": "Starting with Rust 1.75, you can use async fn directly inside traits." },
      { "type": "heading", "level": 2, "text": "What Changed" },
      { "type": "list", "ordered": false, "items": ["Works in all stable traits", "No heap allocation for simple cases"] }
    ]
  }
}

​

Cache Freshness

{
  "urls": ["https://example.com"],
  "ttl": 3600
}

• Omit ttl to accept any cached entry.
• Set ttl to 0 when you want a live fetch.
• Set ttl to a positive integer to accept cached entries younger than that many seconds.

​

Conditional Requests

{
  "urls": ["https://example.com"],
  "if_none_match": "W/\"abc123\"",
  "include_etag_and_last_modified": true
}

• if_none_match and if_modified_since are single-URL only — combining either with a batch of URLs returns a 400.
• When the origin confirms nothing changed, the result comes back with not_modified: true so you can skip re-processing.
• Fetch persists nothing — you own storing and replaying the validators.

​

CSS Selector Scoping

{
  "urls": ["https://example.com/blog/post"],
  "include_selectors": ["article"],
  "exclude_selectors": [".comments", ".newsletter-signup"]
}

• Selected content is returned verbatim in your requested format — automatic boilerplate removal is bypassed. Page-level metadata (title, description, etc.) still comes from the full document.
• exclude_selectors is applied first, then include_selectors scopes what remains.
• If some entries match and others don’t, the URL still succeeds and the misses are listed in the result’s unmatched_selectors. If no entry matches anything, that URL fails with selector_not_matched in errors[], carrying unmatched_selectors plus candidate_selectors retry hints — agents can retry with include_selectors drawn from that list. exclude_selectors entries that match nothing are a no-op.

​

Supported Content Types

​

Fetch Intent

• purpose is always optional. Omitting it leaves fetch behaviour unchanged.
• Keep it to a short phrase or sentence (maximum 2000 characters), for example Compare pricing tiers across vendors for a procurement report.

​

Read Next