Jina Reader API: r.jina.ai and s.jina.ai Headers, Examples, and Limits

The Jina Reader API turns any URL into LLM-ready text: request https://r.jina.ai/ followed by the page URL and markdown comes back, while request headers control format, scope, timing and caching. Its sibling s.jina.ai searches the web and returns the content of each result, and it needs an API key. What follows is a 60-second quickstart, every documented header in one reference, copy-paste curl recipes, and the limits as of September 2026.

What Jina Reader does

Reader is Jina AI's hosted fetch-and-convert service; Jina AI has been part of Elastic since October 2025. It loads a page, using a headless browser when needed, and returns it as markdown, HTML, text, a screenshot or JSON. It reads PDFs by URL, and since December 2025 it also accepts uploaded PDF and Office files. s.jina.ai runs the same pipeline over search results. There is no SDK: the API is plain HTTP, with an official CLI and MCP server alongside it.

Quickstart: read a page in 60 seconds

No account is needed for a first call:

curl 'https://r.jina.ai/https://example.com'

The default response is plain text: a header block with Title:, URL Source: and Published Time: lines, an optional Warning: line, then Markdown Content: followed by the page. Response headers include x-usage-tokens, x-ratelimit-limit and x-ratelimit-remaining, which is enough to meter usage from a script.

If you searched for r.jina.ai/?url=, the documented way to pass the target as a parameter instead of a path is a POST with a url body field. You need it whenever the route lives after a #, because browsers never send the fragment to a server:

curl -X POST 'https://r.jina.ai/' -d 'url=https://example.com/#/route'

Auth, API keys and rate limits

Send your key as a bearer token: Authorization: Bearer <JINA_API_KEY>. One key covers Jina's Reader, Embeddings, Reranker, Classifier and Segmenter APIs, and they share its token balance. Keys don't expire, and you can revoke them in the API dashboard.

Limits as of September 2026, from Jina's Reader page:

Limits are counted per IP without a key and per key with one, in requests and tokens per minute, whichever you hit first.

Billing is prepaid in tokens. Every new key comes with 10 million free tokens, a tier Jina's price table labels "Non-commercial use only (CC-BY-NC)." Failed requests aren't charged, and ReaderLM-v2 requests cost three times the tokens. Paid token packs are listed on Jina's Reader page.

r.jina.ai header reference

Every option below is a request header. Header names are case-insensitive (Jina's own examples mix X-Respond-With and x-respond-with), most have a camelCase twin for POST bodies, and s.jina.ai accepts the same set. A dash in the Values column means Jina's reference lists no values.

Output format headers

X-Respond-With values, per Jina's docs: content applies readability filtering, markdown skips it, html returns documentElement.outerHTML, text returns document.body.innerText, screenshot returns the URL of a viewport screenshot, pageshot captures the full page, and frontmatter returns markdown with YAML front matter.

Content selection headers

Engine, timing and cache headers

Links, images and media headers

The OpenAPI spec spells the links header X-With-links-Summary; since header names are case-insensitive, either works.

Network, identity and session headers

Markdown style headers

Some options have no header and go in the POST body: viewport ({width, height}), injectPageScript and injectFrameScript (JavaScript that runs before extraction, with a window.waitForSelector() helper), plus html, file, pdf and url. For structured extraction with ReaderLM-v2, the OpenAPI spec documents jsonSchema and instruction as query or body parameters, not headers.

Recipes

Each example below is copied from Jina's README or cookbook, or uses one documented header. Add your Authorization header to any of them to get keyed rate limits.

Clean markdown for an LLM

The default content mode keeps the main content; markdown converts the whole page. For RAG ingestion, frontmatter moves the title and metadata into YAML front matter:

curl -H 'X-Respond-With: frontmatter' 'https://r.jina.ai/https://example.com'

Or start from a preset, which fills in only the options you haven't set:

curl https://r.jina.ai/https://example.com/article \
  -H 'x-preset: index'

To control cost, X-Max-Tokens truncates long pages and X-Token-Budget rejects them outright.

Target and remove selectors

When you know the site's template, scope the read to the article and strip the noise inside it:

curl https://r.jina.ai/https://example.com/blog/post-slug \
  -H 'x-target-selector: article.post-body' \
  -H 'x-remove-selector: nav, .related-posts, .comments, footer'

X-Target-Selector also waits for its selector to appear, so you rarely need it and X-Wait-For-Selector together.

Wait for JavaScript-rendered content

# wait for network idle or until timeout
curl 'https://r.jina.ai/https://example.com/' -H 'x-timeout: 10'
 
# wait for a specific element
curl 'https://r.jina.ai/https://example.com/' -H 'x-wait-for-selector: #content'

X-Timeout accepts up to 180 seconds. For finer control, X-Respond-Timing picks the snapshot moment, from html through mutation-idle (at least 0.2 seconds of DOM quiet) to network-idle. Send X-Engine: browser to force headless Chrome on a page that renders on the client.

Screenshots

curl 'https://r.jina.ai/https://example.com' -H 'X-Respond-With: screenshot'

screenshot returns the URL of a viewport screenshot, and pageshot captures the full page. The MCP server offers the same thing as capture_screenshot_url.

JSON output

curl -H "Accept: application/json" https://r.jina.ai/https://en.m.wikipedia.org/wiki/Main_Page

The page text is at data.content, next to title, url, publishedTime and usage.tokens. Add X-With-Links-Summary or X-With-Images-Summary and the lists appear at data.links and data.images.

Streaming and ReaderLM-v2

Accept: text/event-stream turns on stream mode. Jina's January 2025 ReaderLM-v2 announcement pairs it with that HTML-to-markdown model:

curl https://r.jina.ai/https://news.ycombinator.com/ -H 'x-engine: readerlm-v2' -H 'Accept: text/event-stream'

That x-engine form is legacy. Current docs select the model with X-Respond-With: readerlm-v2. Jina marks it experimental, and it costs three times the tokens.

Cache control

curl 'https://r.jina.ai/https://example.com' -H 'X-No-Cache: true'

Reader caches recent fetches and flags cached responses with a warning. X-No-Cache: true bypasses the cache, X-Cache-Tolerance sets acceptable staleness in seconds, and DNT: 1 skips caching and tracking.

Proxies and cookies

X-Proxy routes the fetch through Jina's proxy and needs a key; per the cookbook, pinning a country needs a premium key. X-Proxy-Url uses your own proxy. X-Set-Cookie replays cookies you already hold but doesn't log in for you. Jina's FAQ says Reader doesn't circumvent website defenses, and a paid key doesn't unlock sites that block Jina.

PDFs and Office files

Any URL ending in .pdf is parsed with PDF.js and returned as markdown; for arXiv, read either the PDF URL or the HTML version. To convert a local file, upload it. Office files go through LibreOffice:

curl -X POST 'https://r.jina.ai/' \
  -F 'file=@./report.pdf' \
  -H 'Accept: application/json' \
  -H 'x-markdown-chunking: s3'

x-markdown-chunking: s3 returns block-level chunks as a JSON array. Pick a single page with X-Page or the page body field, both 1-indexed. Uploads are cached by the SHA-256 hash of the file's bytes.

Image captions for text-only models

curl -H "X-With-Generated-Alt: true" https://r.jina.ai/https://en.m.wikipedia.org/wiki/Main_Page

Captioning is opt-in. Images without alt text come back as ![Image [idx]: [caption]](url), and per the OpenAPI spec the header doesn't work when X-Respond-With is set.

Searching with s.jina.ai

s.jina.ai runs your query on the web, then reads each top result through Reader, so your agent gets full page content instead of titles and snippets. It needs a key. Here is Elastic's tutorial example, which also asks for results only:

curl "https://s.jina.ai/Elastic+Jina" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Respond-With: no-content"

The OpenAPI spec documents two paths: /{q}, as above, and /search with a q query parameter. Jina's Reader page also shows the https://s.jina.ai/?q= form. Encode the query in each case:

curl 'https://s.jina.ai/search?q=jina+reader' -H 'Authorization: Bearer <YOUR_API_KEY>'

In-site search, from the README. That example omits the Authorization header it now needs:

curl 'https://s.jina.ai/When%20was%20Jina%20AI%20founded%3F?site=jina.ai&site=github.com'

Prefer the site parameter to the X-Site header, which only Jina's plain-text guide lists. Each search costs a fixed token amount, starting from 10,000. s.jina.ai gets its web results from third-party engines: Elastic's tutorial says the hosted service searches Google, and the open-source code queries Google and Bing, plus an optional provider=reader mode over Reader's own cache of pages it has read.

Calling Jina Reader from an agent

Jina runs an official remote MCP server, https://mcp.jina.ai/v1, over Streamable HTTP (with /sse kept as a legacy alias). The repo is jina-ai/MCP, Apache-2.0. Add it to Claude Code with the command from its README:

claude mcp add -s user --transport http jina https://mcp.jina.ai/v1 \
  --header "Authorization: Bearer ${JINA_API_KEY}"

Its tools include read_url, parallel_read_url, capture_screenshot_url, search_web, search_web_deep, search_arxiv and extract_pdf. The read and screenshot tools work without a key at the keyless limit; search tools need one. Two controls matter:

• Trim the toolset with URL parameters such as include_tools, exclude_tags or include_tags, for example https://mcp.jina.ai/v1?include_tags=search,read.
• Watch truncation. Jina says Claude Code caps MCP tool responses at 25k tokens, so the server truncates read_url output unless you set max_tokens (0 disables it). read_url also takes question, chunk_size and topk to return reranked passages.

Remote-server scopes and debugging are covered in adding MCP servers to Claude Code. Outside MCP, any plain HTTP tool can call Reader, and Jina's official CLI (pip install jina-cli) adds jina read and jina search. For a multi-source research loop, see the web-research-pipeline skill.

Running Jina Reader locally (self-hosting)

The jina-ai/reader repo is the Apache-2.0 open-source branch of the code behind r.jina.ai and s.jina.ai, re-synced with the hosted service in April 2026. From the README:

docker pull ghcr.io/jina-ai/reader:oss
docker run --rm -p 3000:8081 ghcr.io/jina-ai/reader:oss
# then: curl http://localhost:3000/https://example.com

The image bundles headless Chrome, LibreOffice and CJK fonts; port 8080 serves h2c and 8081 serves HTTP/1.1. It runs stateless by default ("no cache, no rate limiting"), with an optional S3-compatible bucket cache. Non-redistributable assets such as the MaxMind GeoLite databases come from npm run assets:download, and the hosted service's MongoDB storage layer isn't included.

The license covers the pipeline, not the models. ReaderLM-v2 and jina-vlm are CC-BY-NC 4.0, so running them in commercial production needs Jina On-Prem. Elastic announced that product on July 27, 2026 and has sold it as its own SKU since August 10, 2026. Calling the hosted APIs commercially needs no separate license.

Who owns Jina now: Elastic since October 2025

Elastic completed its acquisition of Jina AI on October 9, 2025, and former CEO Han Xiao became Elastic's VP of AI. Elastic's FAQ says the Reader, Embeddings and Reranker APIs "continue to be developed and maintained" and work as before, except for entities or countries subject to U.S. export controls. Endpoints, headers and keys are unchanged; contracts, data-processing terms and support now run through Elastic.

Failure modes and fixes

When to use something else

Reader fits "read this URL" and "search and read the top results" with no integration work. Use Firecrawl to crawl or map whole sites at volume, Exa for semantic search on its own index, and Tavily, acquired by Nebius in February 2026, for search, extract and crawl behind one key. If the task needs logins or clicks, you need browser agents.

For the full field, read the best web search APIs for AI agents. For how search and fetch fit together, read getting web data into AI agents.