Skip to main content
A reviewer asks when an HTTP cache must revalidate a stored response and which headers control it. The answer is in RFC 9111 and three MDN pages you already have, and you want it grounded in those pages, with a citation for each claim. This recipe uses two Perplexity APIs. The Context API, with the highlights format, takes the URLs and the question and returns only the passages from each page that answer it: about 6,800 characters across all four pages, where RFC 9111 alone is about 79,000 characters of Markdown. The Agent API then turns those passages into an answer that cites each source by number. You skip pasting whole pages into a prompt and building your own retrieval. The script takes a text file of URLs and a question. It prints the answer, its numbered sources, the URLs it skipped and why, and the cost each API reported.

A live run of this recipe on November 17, 2026. The terminal shows the script's real output, paced for reading. The step captions and API panels were added for the recording.

What you need

  • Python 3.11 or newer on macOS or Linux.
  • A Perplexity API key from the API Console. One key works for both APIs.
  • URLs to public pages you are permitted to read.
The Perplexity Python library has no Context API resource, so this recipe calls both endpoints with httpx.

The URLs

Save this as urls.txt, one URL per line. The first four pages cover HTTP caching. The last two fail on purpose, so you can see how failures come back: the Context API blocks httpbin.org/delay/20, and rfc99999 does not exist.
urls.txt

How the script works

context_qa.py has four functions, one per step.
  1. Batch. batches drops duplicate URLs and splits the list into requests of at most --batch-size URLs. Your usage tier caps the URLs in one request: 10 on tier 0, 15 on tiers 1 to 3, 25 on tiers 4 and 5, and never more than 50. The default of 10 works on every tier. A batch over your cap fails with 400 and the message urls must contain at most N URLs for this account.
  2. Fetch highlights. fetch posts each batch to POST /v1/context with formats: ["highlights"], your question as highlights.query, and highlights.max_tokens_per_url from --tokens (default 512). On a 429 it waits for Retry-After and retries, up to three times.
  3. Keep what loaded. The API returns HTTP 200 even when some URLs fail, and each result carries its own status. collect keeps results whose status.type is ok and that have highlights, reports the rest to stderr with their status.type and the site’s HTTP code, and sums usage.cost.total_cost. Failed URLs are not billed.
  4. Answer with citations. build_context numbers the kept pages and labels each block of highlights with metadata.source_url. answer sends the question and those blocks to POST /v1/agent with no tools, so the model answers only from the passages and cites them as [1], [2], and so on. The numbers in the printed source list match the prompt.
--max-age sets max_age_seconds: the Context API returns a stored copy of a page only if it was fetched within that many seconds, and fetches the page live otherwise. The default is 172800 seconds (two days), and 0 fetches every page live.
context_qa.py

Run it

--batch-size 3 splits the six URLs into two Context API requests. The skipped URLs go to stderr and everything else goes to stdout. This is the output of a run on November 17, 2026:
Output
The two failed URLs did not reach the prompt, and the $0.0040 Context API cost covers the four pages that returned content. origin=cached means the API returned a stored copy, and fetched_at is when that copy was fetched. The answer cites sources by number, but the script does not check that each cited passage supports the sentence that cites it.

Test it offline

test_context_qa.py checks batching, result filtering, context assembly, and the requests main sends, using responses trimmed from recorded runs. It replaces the network with httpx.MockTransport, so it needs no API key and makes no API calls.
test_context_qa.py
Output

Take it further

  • Feed it URLs you did not pick by hand: the url fields from a Search API response, the links in a pull request, or the pages in a vendor’s changelog.
  • Ask a different question of the same URLs. Highlights are computed per query, so the same reading list answers many questions, and stored copies within --max-age are returned without a live fetch.
  • Raise --tokens when the question needs longer passages, and --batch-size up to your tier’s cap to cover more pages per request.

Notes

  • Highlights for the same page can differ between live fetches. Two live fetches of RFC 9111 thirteen seconds apart, with the same query and token budget, returned different passages.
  • Check origin and fetched_at when the age of a page matters, and lower --max-age if the stored copy is too old.
  • total_cost is the list price in USD that the API reports, not the amount charged.