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",
  "proxy_config": {
    "country_code": "US"
  },
  "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
​
proxy_config
object
Route the request through a proxy in a specific country. Useful for geo-restricted content.
{ "country_code": "US" }
See Proxies for supported country codes.
​
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 from <title> or og:title meta tag. null if not found.
​
description
string | null
Meta description from <meta name="description"> or og: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.
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
Description of the failure (e.g. "fetch timeout", "Invalid or disallowed URL").

​
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. Common failure scenarios:
ScenarioExample error value
Page timed out"fetch timeout"
Anti-bot protection triggered"bot protection detected"
No extractable content"no extractable content"
Disallowed or invalid URL"Invalid or disallowed URL"
Proxy tunnel failed"proxy tunnel failed"
Per-URL fetch failures are not HTTP errors. They appear as entries in errors[] alongside a 200 response.

​
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.

Fetch Overview

First request, response shape, and product routing

Authentication

API key setup and troubleshooting

Proxies

Supported country codes and proxy configuration

Error Codes

Full list of API error codes