Fetch Examples

Real-world examples for the Fetch API

Fetch a Single Page

Extract content from any URL as clean Markdown:

Python

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)

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:

Python

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}")

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.

Python

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)

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.

Python

from tinyfish import TinyFish

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

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

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

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

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": []
}

Changed

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

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 Links

Get all hyperlinks and image URLs from a page:

Python

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}")

Fetch as HTML

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

Python

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])

---

Related

Fetch Reference

Full parameter, response, and content type docs

Search Examples

Web search with geo-targeting