Fetch Examples

Fetch a Single Page

Extract content from any URL as clean Markdown:

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=["https://example.com"],
    format="markdown",
)

page = result.results[0]
print(f"Title: {page.title}")
print(page.text)

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

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: ["https://example.com"],
  format: "markdown",
});

const page = result.results[0];
console.log(`Title: ${page.title}`);
console.log(page.text);

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

Output:

{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com/",
      "language": "en",
      "text": "This domain is for use in documentation examples without needing permission...",
      "format": "markdown"
    }
  ],
  "errors": []
}

Batch Fetch

Fetch up to 10 URLs in a single request. Failed URLs appear in errors[] without affecting the rest:

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=[
        "https://example.com",
        "https://httpbin.org/html",
        "https://nonexistent.invalid",
    ],
    format="markdown",
)

for page in result.results:
    print(f"OK: {page.url} → {page.text[:80]}")

for err in result.errors:
    print(f"FAIL: {err.url} → {err.error}")

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

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: [
    "https://example.com",
    "https://httpbin.org/html",
    "https://nonexistent.invalid",
  ],
  format: "markdown",
});

for (const page of result.results) {
  console.log(`OK: ${page.url} → ${page.text.slice(0, 80)}`);
}

for (const err of result.errors) {
  console.log(`FAIL: ${err.url} → ${err.error}`);
}

curl -s -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://httpbin.org/html",
      "https://nonexistent.invalid"
    ],
    "format": "markdown"
  }'

Fetch with Intent

Pass the optional purpose parameter to state why you are fetching — the goal or task the content will be used for. It is always optional, but supplying it gives the fetch additional intent signal beyond the raw URLs, helping deliver better-quality results.

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=["https://example.com/pricing"],
    purpose="Compare pricing tiers across vendors for a procurement report",
)
print(result.results[0].text)

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

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: ["https://example.com/pricing"],
  purpose: "Compare pricing tiers across vendors for a procurement report",
});
console.log(result.results[0].text);

curl -s -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing"],
    "purpose": "Compare pricing tiers across vendors for a procurement report"
  }'

Control Cache Freshness

Use ttl when you need to bound how old a cached page can be. Set ttl to 0 when you want a live fetch, or to a positive number of seconds to accept cached entries younger than that window.

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=["https://example.com"],
    ttl=0,
)
print(result.results[0].text)

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

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

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

Detect Page Changes with Conditional Requests

Save a page’s etag, then replay it on your next fetch to skip re-processing content that hasn’t changed. Conditional requests are a stateless pass-through — Fetch doesn’t store the validators for you. 1. Bootstrap: fetch once and save the etag

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

Output:

{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com/",
      "text": "This domain is for use in documentation examples without needing permission...",
      "format": "markdown",
      "etag": "W/\"abc123\"",
      "last_modified": "Wed, 21 Oct 2015 07:28:00 GMT"
    }
  ],
  "errors": []
}

Save etag (or last_modified) somewhere durable, keyed by URL. 2. Later: replay the etag to check for changes

curl -s -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com"],
    "if_none_match": "W/\"abc123\"",
    "include_etag_and_last_modified": true
  }'

Unchanged
Changed

The origin confirms nothing changed — skip re-processing:

{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com/",
      "text": null,
      "format": "markdown",
      "not_modified": true,
      "etag": "W/\"abc123\"",
      "last_modified": "Wed, 21 Oct 2015 07:28:00 GMT"
    }
  ],
  "errors": []
}

The page changed — fresh content plus a new etag to save for next time:

{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com/",
      "text": "This domain now includes updated documentation examples...",
      "format": "markdown",
      "etag": "W/\"def456\"",
      "last_modified": "Thu, 02 Jul 2026 12:00:00 GMT"
    }
  ],
  "errors": []
}

Scope Extraction to Part of the Page

Use include_selectors to extract only the elements you care about, and exclude_selectors to strip noise (removed before include_selectors is applied). Selected content is returned verbatim in the requested format — automatic boilerplate removal is bypassed — while page-level metadata (title, description, etc.) still comes from the full document.

curl -s -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/blog/post"],
    "format": "markdown",
    "include_selectors": ["article", "aside.related"],
    "exclude_selectors": [".comments", ".newsletter-signup"]
  }'

Output:

{
  "results": [
    {
      "url": "https://example.com/blog/post",
      "final_url": "https://example.com/blog/post",
      "title": "Post Title",
      "text": "# Post Title\n\nOnly the article content, with comments and the newsletter signup removed...",
      "format": "markdown",
      "unmatched_selectors": ["aside.related"]
    }
  ],
  "errors": []
}

Here article matched but aside.related didn’t — a partial miss. The URL still succeeds with the matched content, and the entries that matched nothing are listed in the result’s unmatched_selectors (omitted when everything matched).

If no include_selectors entry matches anything on a page, that URL fails with the per-URL error code selector_not_matched in errors[] — there is no silent full-page fallback. The error carries unmatched_selectors (what missed) and candidate_selectors (up to 10 landmark tags and #id selectors found on the page), so agents can retry with include_selectors drawn from candidate_selectors. exclude_selectors entries that match nothing are simply a no-op.

Extract Ranked Passages with Highlights

Add a highlights object with a question to pull the passages that best answer it from each page — ranked, and quoted word-for-word from the page. Passages are extracted, never generated, so they’re citable evidence with zero fabrication risk. Highlights is in beta, enabled per-account — requests from an account that isn’t enabled return 403 FORBIDDEN.

curl -s -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/"],
    "format": "markdown",
    "highlights": {
      "query": "what does TinyFish do and who uses it",
      "max_snippets": 3
    }
  }'

Output:

{
  "results": [
    {
      "url": "https://www.tinyfish.ai/",
      "final_url": "https://www.tinyfish.ai/",
      "title": "TinyFish — Web Infrastructure for AI Agents",
      "text": null,
      "format": "markdown",
      "highlights": [
        { "text": "Teams use TinyFish when the work depends on dynamic pages, authenticated flows, structured outputs, and production reliability...", "rank": 1 },
        { "text": "One config change gives your agents Search, Fetch, Browser, and Agent. MCP-native, so it works with Claude, Cursor, and any MCP-compatible client...", "rank": 2 },
        { "text": "Your model reasons. TinyFish gives it the live web. Default web access returns cached results. TinyFish hits the live page...", "rank": 3 }
      ]
    }
  ],
  "errors": []
}

text is null because a highlights request returns just the passages by default — set highlights.include_full_page_text: true to also receive the full page markdown.

An empty highlights array means the page was fetched and analyzed and does not answer the query — a calibrated “nothing here”, not a failure. The API may also return passages that are related to the query without directly answering it, so treat highlights as candidate evidence to extract from: if the asked-for fact isn’t in the passages, the correct conclusion is “not on this page.”

Extract Links

Get all hyperlinks and image URLs from a page:

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=["https://www.tinyfish.ai/"],
    format="markdown",
    links=True,
    image_links=True,
)

page = result.results[0]
print(f"Found {len(page.links)} links and {len(page.image_links)} images")

for link in page.links[:5]:
    print(f"  → {link}")

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

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: ["https://www.tinyfish.ai/"],
  format: "markdown",
  links: true,
  image_links: true,
});

const page = result.results[0];
console.log(`Found ${page.links.length} links and ${page.image_links.length} images`);

for (const link of page.links.slice(0, 5)) {
  console.log(`  → ${link}`);
}

curl -s -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/"],
    "format": "markdown",
    "links": true,
    "image_links": true
  }'

Fetch as HTML

Get semantic HTML instead of Markdown — useful for preserving structure:

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=["https://httpbin.org/html"],
    format="html",
)

page = result.results[0]
print(page.text[:300])

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

const client = new TinyFish();
const result = await client.fetch.getContents({
  urls: ["https://httpbin.org/html"],
  format: "html",
});

const page = result.results[0];
console.log(page.text.slice(0, 300));

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

Fetch Reference

Full parameter, response, and content type docs

Search Examples

Web search with geo-targeting

Start Here

Agent API

Search API

Monitor (Beta)

Fetch API

Browser API

Research API (Beta)

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Fetch a Single Page

Batch Fetch

Fetch with Intent

Control Cache Freshness

Detect Page Changes with Conditional Requests

Scope Extraction to Part of the Page

Extract Ranked Passages with Highlights

Extract Links

Fetch as HTML

Fetch Reference

Search Examples

​Fetch a Single Page

​Batch Fetch

​Fetch with Intent

​Control Cache Freshness

​Detect Page Changes with Conditional Requests

​Scope Extraction to Part of the Page

​Extract Ranked Passages with Highlights

​Extract Links

​Fetch as HTML

​Related

Fetch Reference

Search Examples

Fetch a Single Page

Batch Fetch

Fetch with Intent

Control Cache Freshness

Detect Page Changes with Conditional Requests

Scope Extraction to Part of the Page

Extract Ranked Passages with Highlights

Extract Links

Fetch as HTML

Related