> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Examples

> Real-world examples for TinyFetch

## Fetch a Single Page

Extract content from any URL as clean Markdown:

```python Python theme={null}
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)
```

```typescript TypeScript theme={null}
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);
```

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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 Python theme={null}
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}")
```

```typescript TypeScript theme={null}
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}`);
}
```

```bash cURL theme={null}
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.

```python Python theme={null}
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)
```

```typescript TypeScript theme={null}
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);
```

```bash cURL theme={null}
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.

```python Python theme={null}
from tinyfish import TinyFish

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

```typescript TypeScript theme={null}
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);
```

```bash cURL theme={null}
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`**

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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**

```bash cURL theme={null}
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
  }'
```

> [tab] Unchanged
>
> The origin confirms nothing changed — skip re-processing:
>
> ```json theme={null}
> {
>   "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": []
> }
> ```

> [tab] Changed
>
> The page changed — fresh content plus a new `etag` to save for next time:
>
> ```json theme={null}
> {
>   "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.

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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).

> [!NOTE]
>
> 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`.

```bash cURL theme={null}
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:**

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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:

```python Python theme={null}
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}")
```

```typescript TypeScript theme={null}
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}`);
}
```

```bash cURL theme={null}
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:

```python Python theme={null}
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])
```

```typescript TypeScript theme={null}
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));
```

```bash cURL theme={null}
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"}'
```

***

## Related

> [card] [Fetch Reference](https://docs.tinyfish.ai/tinyfetch/reference.md)
>
> Full parameter, response, and content type docs

> [card] [Search Examples](https://docs.tinyfish.ai/tinysearch/examples.md)
>
> Web search with geo-targeting


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.