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.
httpx.
The URLs
Save this asurls.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.
- Batch.
batchesdrops duplicate URLs and splits the list into requests of at most--batch-sizeURLs. 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 with400and the messageurls must contain at most N URLs for this account. - Fetch highlights.
fetchposts each batch toPOST /v1/contextwithformats: ["highlights"], your question ashighlights.query, andhighlights.max_tokens_per_urlfrom--tokens(default 512). On a429it waits forRetry-Afterand retries, up to three times. - Keep what loaded. The API returns HTTP
200even when some URLs fail, and each result carries its ownstatus.collectkeeps results whosestatus.typeisokand that have highlights, reports the rest to stderr with theirstatus.typeand the site’s HTTP code, and sumsusage.cost.total_cost. Failed URLs are not billed. - Answer with citations.
build_contextnumbers the kept pages and labels each block of highlights withmetadata.source_url.answersends the question and those blocks toPOST /v1/agentwith notools, 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
context_qa.py
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
$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
test_context_qa.py
test_context_qa.py
Output
Take it further
- Feed it URLs you did not pick by hand: the
urlfields 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-ageare returned without a live fetch. - Raise
--tokenswhen the question needs longer passages, and--batch-sizeup 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
originandfetched_atwhen the age of a page matters, and lower--max-ageif the stored copy is too old. total_costis the list price in USD that the API reports, not the amount charged.