Skip to main content

​
Endpoint

POST https://api.fetch.tinyfish.ai
All requests require an X-API-Key header. See Authentication.

​
Request

{
  "urls": ["https://example.com"],
  "format": "html",
  "links": false,
  "image_links": false
}

​
Parameters

​
urls
string[]
required
URLs to fetch and extract. Maximum 10 URLs per request.All URLs must use http or https. Private IP addresses, localhost, and cloud metadata endpoints are rejected.
​
format
string
default:"markdown"
Output format for the text field in each result. One of:
  • html — semantic HTML
  • markdown — clean Markdown, recommended for LLMs (default)
  • json — structured document tree
​
links
boolean
default:"false"
When true, include all <a href> URLs found on the page in the links field.
​
image_links
boolean
default:"false"
When true, include all <img src> URLs found on the page in the image_links field.

​
Response

{
  "results": [...],
  "errors": [...]
}

​
results[]

One entry per successfully fetched URL.
​
url
string
The original requested URL.
​
final_url
string
The URL after any redirects. May differ from url.
​
title
string | null
Page title, preferring og:title over <title>. null if not found.
​
description
string | null
Meta description, preferring og:description over <meta name="description">. null if not found.
​
language
string | null
Detected page language (e.g. "en"). null if undetectable.
​
author
string | null
Author from meta tags. null if not found.
​
published_date
string | null
Publication date, if detectable. null if not found.
​
text
string | object
Extracted page content. Format depends on the format request parameter:
  • string when format is "html" or "markdown"
  • object (document tree) when format is "json"
​
links
string[]
All <a href> URLs on the page, resolved to absolute URLs. Only present when links: true was requested.
​
image_links
string[]
All <img src> URLs on the page, resolved to absolute URLs. Only present when image_links: true was requested.
​
latency_ms
number | null
Time to fetch and extract this URL, in milliseconds. null if unavailable.
​
format
string
Output format used for the text field. Echoes the request format parameter ("markdown", "html", or "json").
Fields that could not be extracted (title, description, language, author, published_date) are omitted from the response when null rather than returned explicitly as null.

​
errors[]

One entry per URL that could not be fetched. Always present, may be empty. Per-URL failures do not affect the rest of the batch.
​
url
string
The URL that failed.
​
error
string
Structured error code identifying the failure type. One of: timeout, bot_blocked, empty_content, invalid_url, proxy_error, fetch_error.

​
SDK Methods

from tinyfish import TinyFish

client = TinyFish()
result = client.fetch.get_contents(
    urls=["https://www.tinyfish.ai/"],
    format="markdown",
)
for page in result.results:
    print(page.title, "→", page.text[:100])

​
Error Codes

HTTP-level errors apply to the entire request.
StatusMeaning
400Invalid request — missing urls, too many URLs (max 10), or bad parameter value
401Missing or invalid API key
429Rate limit exceeded
500Internal server error
Per-URL errors appear in errors[] alongside a 200 response. The error field is one of these codes:
Error codeMeaning
timeoutPage did not finish loading within the request deadline
bot_blockedSite returned a bot-protection challenge (Cloudflare, Incapsula)
empty_contentBrowser returned HTML but no extractable text found
invalid_urlURL rejected before fetch (private IP, invalid scheme, disallowed host)
proxy_errorProxy tunnel failed — site may be reachable directly
fetch_errorCatch-all for other failures
Per-URL fetch failures are not HTTP errors. They appear as entries in errors[] alongside a 200 response.
Each URL has a 240-second backend timeout. If the page doesn’t respond within 240 seconds, that URL returns a timeout error in errors[] while the rest of the batch continues. Set your client-side timeout to at least 500 seconds for batch requests with multiple URLs.

​
Rate Limits

Limits apply per API key, measured in URLs per minute across all requests.
PlanURLs / minute
Free Trial25
Pay As You Go50
Starter100
Pro250
When the limit is exceeded, the API returns HTTP 429. Implement exponential backoff before retrying.

​
Billing

1 credit = 15 URL fetches. Failed URLs (those that appear in errors[]) are not charged.

​
Supported Content Types

Content TypeBehavior
HTMLFull text extraction with formatting
PDFText content extracted
JSONRaw JSON returned as text
Plain textFull text returned
Images (PNG, JPG)Not supported — returns an error indicating no extractable content

​
Usage Endpoint

Retrieve a paginated history of your fetch operations. 
GET https://api.fetch.tinyfish.ai/usage
All requests require an X-API-Key header. See Authentication.

​
Query Parameters

​
start_after
string (ISO 8601)
Filter results created after this timestamp. Example: 2026-01-01T00:00:00Z
​
end_before
string (ISO 8601)
Filter results created before this timestamp. Example: 2026-02-01T00:00:00Z
​
status
string
Filter by result status. One of: completed, failed.
​
limit
integer
default:"100"
Maximum number of items per page. Range: 1-1000.
​
page
integer
default:"1"
Page number for pagination.

​
Response

{
  "items": [...],
  "total": 42,
  "limit": 100,
  "page": 1,
  "total_pages": 1,
  "has_more": false
}

​
items[]

​
id
string
Unique identifier for the fetch result.
​
url
string
The original requested URL.
​
final_url
string
The URL after any redirects.
​
title
string | null
Page title, if detected.
​
description
string | null
Meta description, if detected.
​
language
string | null
Detected page language (e.g. "en").
​
author
string | null
Page author, if detected.
​
published_date
string | null
Published date, if detected.
​
format
string
The format used for extraction: markdown, html, or json.
​
status
string
Result status: completed or failed.
​
request_origin
string
Where the request originated: api, cli, python-sdk, js-sdk, mcp, etc.
​
request_id
string | null
The request ID that grouped this URL with others in a batch.
​
text_length
integer | null
Length of the extracted text content in characters. The full text is not included in usage responses.
​
links_count
integer
Number of links found on the page.
​
image_links_count
integer
Number of image links found on the page.
​
latency_ms
number | null
Time taken to fetch and extract the page, in milliseconds.
​
created_at
string (ISO 8601)
Timestamp when the fetch was executed.
​
error
string | null
Error message if the fetch failed. null for successful fetches.

​
Error Codes

StatusMeaning
400Invalid query parameters
401Missing or invalid API key
403Fetch API access is not enabled for this account
500Internal server error

Fetch Overview

First request, response shape, and product routing

Authentication

API key setup and troubleshooting

Error Codes

Full list of API error codes