Markdown APIs for Web Pages: Documented Outputs & Requirements

markdown, HTML, JSON, screenshot

For this task: Choose Markdown for readable page content or a JSON schema for extracted fields. The HTTP response envelope is separate from the requested format; set cache age intentionally and inspect target status before accepting the result.[1][2]

Known page or whole site

POST /v2/scrape reads one URL. For a site traversal, /v2/crawl starts an asynchronous job. Give crawl an explicit page limit and path scope before starting.[1][5]

Markdown response

Request formats: ["markdown"]. Raw HTTP returns content in data.markdown inside a success/data envelope; SDKs return the data object directly.[1]

HTML choices

Use formats: ["html"] for cleaned page HTML at data.html. Use formats: ["rawHtml"] for unmodified page HTML at data.rawHtml. These formats preserve markup; Markdown is the text-oriented choice.[1]

Structured fields

Use a formats object with type: "json" and a prompt or JSON Schema for fields from a known page. Raw HTTP returns the extracted object at data.json. A JSON response envelope alone does not request extraction. Agent is a separate choice when source URLs must be discovered.[1][2]

Freshness

The documented cache default permits data up to two days old. Set maxAge: 0 when the task needs a fresh fetch; this does not guarantee that the target returns the desired page.[1]

Accepting the response

An API HTTP 200 or success: true is not sufficient. Inspect data.metadata.statusCode and the requested content: a captured target 403 or 404 can be returned and billed.[1][3]

Credit decision

For an ordinary returned page, Markdown uses the 1-credit base. JSON extraction totals 5 credits before other options. Extra modifiers stack; optional browser sessions have a separate billing basis.[3][2]

No-document exceptions

Ordinary scrapes that return no document generally cost 0 credits. Paid guards, threat scans and other documented options have exceptions; a returned error page is still a document.[3]

Authentication and capacity

Anonymous Scrape has daily per-IP limits. An account API key uses the team plan and shared request limits. Crawl, Map and batch requests require authentication.[4]

Rate limits versus target errors

A Firecrawl 429 can mean request-rate or concurrency limits. Inspect the response, respect Retry-After when provided and reduce load; repeating a captured target error is a separate decision.[4][6]

Credits per returned page, with option charges. An ordinary scrape is 1 credit; schema-guided JSON adds 4. Account plans and anonymous limits are separate. Check detailed billing before enabling extra options.

markdown, text, HTML, JSON

For this task: The default content mode extracts main-content Markdown. X-Respond-With: markdown keeps full-page content; Accept: application/json changes the response wrapper. Use cache and selector controls when the returned text is stale or incomplete.[1][2][3]

Known URL first

Prefix a complete URL with https://r.jina.ai/ to read that page, for example https://r.jina.ai/https://example.com. The separately authenticated s.jina.ai search endpoint has its own terms.[1][2]

Main content or full page

The default content mode extracts readable page content as Markdown. X-Respond-With: markdown returns full-page Markdown without the readability filter. Use the default for an article body; choose full-page mode when surrounding page text matters.[2][3]

JSON wrapper versus fields

Accept: application/json requests a JSON response with page URL, title and content. It does not ask Reader to extract your own JSON Schema fields. X-Respond-With selects the content representation inside the response.[1][2][3]

HTML and text choices

Set X-Respond-With: html for HTML or X-Respond-With: text for plain text. Select the representation your application will process before comparing output size or token usage.[2][3]

Freshness

Use X-No-Cache: true or X-Cache-Tolerance: 0 when cached output is unsuitable. Published sources give different cache lifetimes, so do not rely on one universal default TTL.[1][2][3]

Missing dynamic content

For a page that needs browser rendering, explicitly choose X-Engine: browser. X-Wait-For-Selector waits for an expected element; X-Target-Selector limits returned content and X-Remove-Selector removes unwanted elements.[1][2][3]

Hash-based routes

A URL fragment after # is normally kept by the HTTP client. For a route such as https://example.com/#/route, POST the full URL in the request body to https://r.jina.ai/ so Reader receives the fragment.[2][3]

Reject or truncate

X-Token-Budget rejects a request when the resulting token cost would exceed the limit. X-Max-Tokens truncates returned content. Choose rejection when completeness matters; use truncation only when partial output is acceptable.[2][3]

Authentication and limits

Basic Reader requests can omit credentials. Send Authorization: Bearer YOUR_JINA_API_KEY for the supplied key’s token balance and rate limits. Anonymous limits are tracked by IP; keyed requests use the key’s limits.[1][3]

Basic anonymous URL reading is rate-limited. Keyed Reader usage draws from the supplied API key’s output-token balance; optional modes can change token usage. Jina documents no token deduction for failed requests. Check the current key quota and rate table.

HTML, JSON, markdown, PNG

For this task: Request formats: ["markdown"]; the documented response places it in data.markdown. Rendering is a separate option and defaults off. Screenshot output enables rendering and can affect pricing.[1][4][3]

Formats

The formats array selects HTML, Markdown, Base64 PNG screenshots and response headers.[1]

Rendering

render defaults to false; true enables JavaScript and auto lets Nimble select the configuration.[1]

Parsing and actions

CSS parsing schemas, browser actions and network-capture rules are supported.[1]

Async processing

Async and batch submissions return before processing finishes; poll task or batch progress for completion.[2]

Billing

Extraction Tools are listed at USD 1 per 1,000 URLs, with charges only for successful requests.[3]

Successful URL extractions; public API pricing lists USD 1 per 1,000 URLs for Extraction Tools.

HTML, JSON, markdown, screenshot

For this task: Markdown uses llm_extract=true with llm_extract_response_type=markdown. This LLM extraction path adds 25 credits to the fetch cost; HTTP 404 responses are also billable.[4][1]

Billing outcomes

The credit policy counts both HTTP 200 and 404 responses as successful, billable requests.[1]

Rendering costs

Standard rendering costs 10 credits; residential plus rendering costs 25; render_js_cheap costs 5 using a limited provider set.[1]

Extraction add-on

llm_extract adds 25 credits on top of base proxy costs.[1]

Cheaper rendering tradeoff

render_js_cheap is intended for simpler sites and does not provide the full upstream provider pool.[2]

Response options

The feature list documents screenshot capture and JSON or Markdown LLM extraction responses.[3]

Monthly API credits determined by target and options; HTTP 200 and 404 responses consume credits.

HTML, JSON, markdown, text, screenshot

For this task: Set return_page_markdown=true for Markdown output. This is separate from AI extraction. JavaScript rendering defaults on, so choose rendering and proxy options before estimating credits.[1]

Rendering default

render_js defaults to true. HTML, page text, Markdown and screenshots are documented output options.[1]

Request credits

Classic requests cost 1 credit without rendering or 5 with it; premium with rendering costs 25 and stealth with rendering costs 75.[1]

Extraction and interaction

CSS extract_rules and js_scenario support structured extraction and page interactions.[1]

Custom proxy

The own_proxy parameter supports a user-supplied proxy provider.[1]

Automatic cost control

GET-only mode=auto chooses a successful rendering/proxy tier; max_cost caps eligible tiers and all-failed auto attempts cost zero.[1]

Monthly API credits; rendering and proxy tier determine base credits, with AI extraction add-ons.

JSON, markdown, text

For this task: Use Extract for a known URL and request format: markdown. The Markdown sits in results[].raw_content inside a JSON response; inspect failed_results for partial failures. Search is a separate call when the source URL is unknown.[2][1]

Unknown source URL

POST /search with a query. Set search_depth: basic and max_results deliberately; results include source URLs and content snippets. A result snippet is a lead to inspect, not the complete source page.[1]

Known source URL

POST /extract directly with urls (one URL or up to 20). Request format: markdown or text. The JSON response wraps each successful page in results with raw_content. Search is unnecessary when the URL is already known.[2]

Content choice

Search returns results[].content snippets; request include_raw_content for cleaned and parsed page content when available, without a guarantee of complete target coverage. Extract format: markdown returns Markdown inside results[].raw_content; format: text selects plain text.[1][2]

Partial result check

An Extract HTTP 200 can include both results and failed_results, or an empty results array if every valid URL fails. Match each returned item to its URL; output order is not guaranteed.[2]

Search credit unit

Basic Search costs 1 account credit per request and advanced costs 2. auto_parameters may select advanced; set search_depth: basic explicitly when the lower unit matters.[3][1]

Extract credit unit

With an account key, basic Extract costs 1 credit per 5 successful URL extractions and advanced costs 2 per 5. Failed URL extractions are not charged. With include_usage: true, usage may show 0 before the total reaches five successful extractions.[3][2]

Direct HTTP access

POST /search and /extract can use X-Tavily-Access-Mode: keyless without an account or API key, subject to rate limits. Alternatively send Authorization: Bearer YOUR_TAVILY_API_KEY for account limits; if both headers are sent, the key takes precedence. The MCP connection has its own client setup.[4][3]

Search and Extract offer free, rate-limited keyless direct HTTP access with X-Tavily-Access-Mode: keyless. With an account key, basic Search costs 1 credit/request and advanced costs 2; basic Extract costs 1 credit per 5 successful URL extractions and advanced costs 2 per 5. Failed URL extractions are not charged. Extract usage can report 0 before five successful URL extractions.