> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grounded Q&A over Your Own URLs with the Context API

> Send URLs and a question to the Context API, get back only the passages from each page that matter to the question, and turn them into an answer that cites each source by number.

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.

<video autoPlay muted loop playsInline controls src="https://mintcdn.com/perplexity/DNmAjyDQT2YpuP8C/docs/assets/images/cookbook/examples/context-api-reading-list-qa-demo.mp4?fit=max&auto=format&n=DNmAjyDQT2YpuP8C&q=85&s=169ac977fd0aafe6df638c511d4c42d1" />

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](https://console.perplexity.ai/project/keys). 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`.

```bash theme={null}
mkdir reading-list-qa && cd reading-list-qa
python3 -m venv .venv && source .venv/bin/activate
pip install httpx==0.28.1 pytest==9.1.1
export PERPLEXITY_API_KEY="your-api-key-here"
```

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

```text urls.txt theme={null}
https://www.rfc-editor.org/rfc/rfc9111.html
https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching
https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control
https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since
https://httpbin.org/delay/20
https://www.rfc-editor.org/rfc/rfc99999.html
```

## 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](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md) 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.

> [accordion] context\_qa.py
>
> ```python context_qa.py theme={null}
> """Answer a question over a list of URLs with Context API highlights and one Agent API call."""
>
> import argparse
> import os
> import sys
> import time
> from pathlib import Path
>
> import httpx
>
> CONTEXT_URL = "https://api.perplexity.ai/v1/context"
> AGENT_URL = "https://api.perplexity.ai/v1/agent"
> MODEL = "openai/gpt-6-luna"
>
> PROMPT = """Answer the question using only the numbered sources below.
> Cite every claim with the source number in brackets, like [2].
> If the sources do not answer part of the question, say which part.
>
> Question: {question}
>
> {context}"""
>
>
> def batches(urls: list[str], size: int) -> list[list[str]]:
>     """Split URLs into requests of at most `size` URLs, keeping order and dropping duplicates."""
>     unique = list(dict.fromkeys(urls))
>     return [unique[i : i + size] for i in range(0, len(unique), size)]
>
>
> def fetch(client: httpx.Client, urls: list[str], question: str, tokens: int, max_age: int) -> dict:
>     """Request highlights for one batch of URLs, waiting out the rate limit up to three times."""
>     body = {
>         "urls": urls,
>         "formats": ["highlights"],
>         "highlights": {"query": question, "max_tokens_per_url": tokens},
>         "max_age_seconds": max_age,
>     }
>     for _ in range(3):
>         response = client.post(CONTEXT_URL, json=body)
>         if response.status_code != 429:
>             break
>         time.sleep(float(response.headers.get("Retry-After", "1")))
>     if response.status_code >= 400:
>         sys.exit(f"Context API {response.status_code}: {response.text}")
>     return response.json()
>
>
> def collect(responses: list[dict]) -> tuple[dict, list[dict], float]:
>     """Turn Context API responses into usable sources, skipped URLs, and total cost.
>
>     Only `ok` results carry content. An `ok` result with no highlights is skipped,
>     because nothing on the page matched the question.
>     """
>     sources, skipped, cost = {}, [], 0.0
>     for data in responses:
>         cost += data["usage"]["cost"]["total_cost"]
>         for result in data["results"]:
>             url, status = result["url"], result["status"]
>             if status["type"] == "ok" and result.get("highlights"):
>                 meta = result["metadata"]
>                 sources[url] = {
>                     "source_url": meta["source_url"],
>                     "title": meta.get("title", ""),
>                     "highlights": result["highlights"],
>                     "fetched_at": meta.get("fetched_at"),
>                     "origin": meta.get("origin"),
>                 }
>             else:
>                 reason = "no matching passage" if status["type"] == "ok" else status["type"]
>                 skipped.append({"url": url, "reason": reason, "status_code": status.get("status_code")})
>     return sources, skipped, cost
>
>
> def build_context(sources: list[dict]) -> str:
>     """Number each source and label its highlights with the URL the API read."""
>     blocks = []
>     for n, source in enumerate(sources, 1):
>         title = f"\nTitle: {source['title']}" if source["title"] else ""
>         blocks.append(f"[{n}] {source['source_url']}{title}\n{source['highlights'].strip()}")
>     return "\n\n".join(blocks)
>
>
> def answer(client: httpx.Client, question: str, context: str) -> tuple[str, float]:
>     """Ask the Agent API for a cited answer. No tools are enabled, so the model sees only the context."""
>     response = client.post(
>         AGENT_URL,
>         json={
>             "model": MODEL,
>             "input": PROMPT.format(question=question, context=context),
>             "max_output_tokens": 1500,
>         },
>     )
>     if response.status_code >= 400:
>         sys.exit(f"Agent API {response.status_code}: {response.text}")
>     data = response.json()
>     text = "".join(
>         part["text"]
>         for item in data["output"]
>         if item["type"] == "message"
>         for part in item["content"]
>         if part["type"] == "output_text"
>     )
>     return text, data["usage"]["cost"]["total_cost"]
>
>
> def main() -> None:
>     parser = argparse.ArgumentParser(description=__doc__)
>     parser.add_argument("urls_file", help="text file with one URL per line")
>     parser.add_argument("question")
>     parser.add_argument(
>         "--batch-size", type=int, default=10, help="URLs per request; 10, 15, 25, or 50 by usage tier"
>     )
>     parser.add_argument("--tokens", type=int, default=512, help="highlight budget per URL")
>     parser.add_argument(
>         "--max-age", type=int, default=172800, help="oldest stored copy to accept, in seconds"
>     )
>     args = parser.parse_args()
>
>     urls = [line.strip() for line in Path(args.urls_file).read_text().splitlines() if line.strip()]
>     headers = {"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"}
>     with httpx.Client(headers=headers, timeout=120) as client:
>         responses = [
>             fetch(client, batch, args.question, args.tokens, args.max_age)
>             for batch in batches(urls, args.batch_size)
>         ]
>         sources, skipped, context_cost = collect(responses)
>         for item in skipped:
>             code = f" (HTTP {item['status_code']})" if item["status_code"] else ""
>             print(f"skipped {item['url']}: {item['reason']}{code}", file=sys.stderr)
>         if not sources:
>             sys.exit("No URL returned highlights for this question.")
>
>         ordered = list(sources.values())
>         text, agent_cost = answer(client, args.question, build_context(ordered))
>
>     print(text)
>     print("\nSources:")
>     for n, source in enumerate(ordered, 1):
>         print(f"[{n}] {source['source_url']}  origin={source['origin']} fetched_at={source['fetched_at']}")
>     print(
>         f"\nContext API requests: {len(responses)}, URLs with highlights: {len(sources)}, skipped: {len(skipped)}"
>     )
>     print(f"List-price cost: Context API ${context_cost:.4f}, Agent API ${agent_cost:.4f}")
>
>
> if __name__ == "__main__":
>     main()
> ```

## Run it

```bash theme={null}
python3 context_qa.py urls.txt "When must a cache revalidate a stored response before reusing it, and which request and response headers control that?" --batch-size 3
```

`--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:

```text Output theme={null}
skipped https://httpbin.org/delay/20: blocked
skipped https://www.rfc-editor.org/rfc/rfc99999.html: crawl_failed (HTTP 404)
A cache must revalidate a stored response before reuse when it is stale; responses become stale after their freshness lifetime expires, such as when `max-age` elapses or the `Expires` time passes. [1][3] A response marked `Cache-Control: must-revalidate` must be successfully validated once stale, while `Cache-Control: no-cache` requires validation before every reuse, even if the response is still fresh. [1][3] A request can also ask for validation before reuse with the `Cache-Control: no-cache` request directive. [3] A cache without a clock must revalidate stored responses on every use. [1]

The controlling headers are `Cache-Control` and `Expires` on the response, and `Cache-Control` on the request. [1][3] Revalidation is commonly performed with a conditional request using `If-None-Match` or `If-Modified-Since`; the latter can be used when the cached response has a `Last-Modified` date, and `If-None-Match` takes precedence when supported. [2][4]

Sources:
[1] https://www.rfc-editor.org/rfc/rfc9111.html  origin=cached fetched_at=2026-11-17T11:07:04Z
[2] https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching  origin=cached fetched_at=2026-11-17T09:04:40Z
[3] https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control  origin=cached fetched_at=2026-11-16T22:54:03Z
[4] https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since  origin=cached fetched_at=2026-11-17T11:45:43Z

Context API requests: 2, URLs with highlights: 4, skipped: 2
List-price cost: Context API $0.0040, Agent API $0.0004
```

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.

> [accordion] test\_context\_qa.py
>
> ```python test_context_qa.py theme={null}
> """Offline tests for context_qa.py. Responses are trimmed from recorded Context API runs."""
>
> import json
> import sys
>
> import httpx
>
> import context_qa
>
> RFC = "https://www.rfc-editor.org/rfc/rfc9111.html"
> MDN = "https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching"
> BLOCKED = "https://httpbin.org/delay/20"
> MISSING = "https://www.rfc-editor.org/rfc/rfc99999.html"
>
>
> def ok_result(url, title, highlights):
>     result = {
>         "url": url,
>         "status": {"type": "ok", "status_code": 200},
>         "metadata": {
>             "source_url": url,
>             "title": title,
>             "fetched_at": "2026-11-17T21:14:17Z",
>             "origin": "live",
>         },
>     }
>     if highlights:
>         result["highlights"] = highlights
>     return result
>
>
> RESPONSE = {
>     "results": [
>         ok_result(RFC, "HTTP Caching", "the cache MUST NOT use that stored response without revalidation"),
>         ok_result(MDN, "HTTP caching", "Stale responses are not immediately discarded."),
>         {"url": BLOCKED, "status": {"type": "blocked", "message": "This URL is blocked."}},
>         {
>             "url": MISSING,
>             "status": {
>                 "type": "crawl_failed",
>                 "status_code": 404,
>                 "message": "The page could not be fetched.",
>             },
>         },
>     ],
>     "usage": {"cost": {"currency": "USD", "total_cost": 0.002}, "fetched_urls": 2},
> }
>
> AGENT_RESPONSE = {
>     "output": [
>         {"type": "reasoning", "summary": []},
>         {
>             "type": "message",
>             "role": "assistant",
>             "content": [{"type": "output_text", "text": "Revalidate once stale [1].", "annotations": []}],
>         },
>     ],
>     "usage": {"cost": {"currency": "USD", "total_cost": 0.0005}},
> }
>
>
> def test_batches_respect_limit_order_and_duplicates():
>     urls = [f"https://example.com/{i}" for i in range(23)]
>     chunks = context_qa.batches(urls + urls[:3], 10)
>     assert [len(c) for c in chunks] == [10, 10, 3]
>     assert [url for chunk in chunks for url in chunk] == urls
>
>
> def test_collect_keeps_ok_results_and_skips_failures():
>     notes = "https://example.org/notes"
>     second = {"results": [ok_result(notes, "Notes", "text")], "usage": RESPONSE["usage"]}
>     sources, skipped, cost = context_qa.collect([RESPONSE, second])
>     assert list(sources) == [RFC, MDN, notes]
>     assert skipped == [
>         {"url": BLOCKED, "reason": "blocked", "status_code": None},
>         {"url": MISSING, "reason": "crawl_failed", "status_code": 404},
>     ]
>     assert round(cost, 6) == 0.004
>
>
> def test_collect_skips_ok_result_without_highlights():
>     response = {"results": [ok_result(RFC, "HTTP Caching", None)], "usage": {"cost": {"total_cost": 0.001}}}
>     sources, skipped, _ = context_qa.collect([response])
>     assert sources == {}
>     assert skipped == [{"url": RFC, "reason": "no matching passage", "status_code": 200}]
>
>
> def test_build_context_numbers_sources_and_handles_missing_title():
>     sources, _, _ = context_qa.collect([RESPONSE])
>     context = context_qa.build_context([sources[RFC], {**sources[MDN], "title": ""}])
>     assert context.startswith(f"[1] {RFC}\nTitle: HTTP Caching\nthe cache MUST NOT")
>     assert f"\n\n[2] {MDN}\nStale responses" in context
>     assert "Title: \n" not in context
>
>
> def test_main_sends_batches_and_one_agent_call(tmp_path, monkeypatch, capsys):
>     question = "When must a cache revalidate?"
>     urls = tmp_path / "urls.txt"
>     urls.write_text(f"{RFC}\n{MDN}\n\n{BLOCKED}\n{MISSING}\n")
>     requests = []
>
>     def handler(request):
>         body = json.loads(request.content)
>         requests.append((request.url.path, body))
>         if request.url.path == "/v1/agent":
>             return httpx.Response(200, json=AGENT_RESPONSE)
>         results = [r for r in RESPONSE["results"] if r["url"] in body["urls"]]
>         return httpx.Response(200, json={"results": results, "usage": RESPONSE["usage"]})
>
>     real_client = httpx.Client
>     monkeypatch.setattr(
>         context_qa.httpx, "Client", lambda **kw: real_client(transport=httpx.MockTransport(handler), **kw)
>     )
>     monkeypatch.setenv("PERPLEXITY_API_KEY", "test")
>     monkeypatch.setattr(sys, "argv", ["context_qa.py", str(urls), question, "--batch-size", "3"])
>     context_qa.main()
>
>     paths = [path for path, _ in requests]
>     assert paths == ["/v1/context", "/v1/context", "/v1/agent"]
>     assert requests[0][1] == {
>         "urls": [RFC, MDN, BLOCKED],
>         "formats": ["highlights"],
>         "highlights": {"query": question, "max_tokens_per_url": 512},
>         "max_age_seconds": 172800,
>     }
>     assert requests[1][1]["urls"] == [MISSING]
>     prompt = requests[2][1]["input"]
>     assert f"[1] {RFC}" in prompt and f"[2] {MDN}" in prompt
>     assert BLOCKED not in prompt and MISSING not in prompt
>     assert "tools" not in requests[2][1]
>
>     out = capsys.readouterr()
>     assert "Revalidate once stale [1]." in out.out
>     assert "skipped https://httpbin.org/delay/20: blocked\n" in out.err
>     assert "Context API $0.0040, Agent API $0.0005" in out.out
> ```

```bash theme={null}
python3 -m pytest -q test_context_qa.py
```

```text Output theme={null}
.....                                                                    [100%]
5 passed
```

## Take it further

* Feed it URLs you did not pick by hand: the `url` fields from a [Search API](https://docs.perplexity.ai/docs/search/quickstart.md) 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.
