Last updated: November 19, 2026
The Perplexity Context API turns a list of URLs into clean Markdown, HTML, links or query-relevant highlights for AI agents. Announced November 17, 2026, it costs $1 per 1,000 successfully fetched URLs, reads 10 to 25 URLs per request depending on your usage tier, and lets you choose between cached and live pages.
Contents
- What the Context API does
- Pricing, limits and parameters
- How to make your first request
- Freshness, conditional requests and timeouts
- Scoring pages with criteria
- Context API vs. Search API and Agent API
- Limitations and tips
- Frequently asked questions
What the Context API does
Perplexity introduced the Context API in a blog post dated November 17, 2026, and its developer account announced on X on November 18 that the API is live.
According to the Context API quickstart, you send a batch of URLs to POST https://api.perplexity.ai/v1/context and get one result per URL, in the same order. Each result can include the page as Markdown, its HTML, its links, the passages most relevant to your query, and metadata such as title, language and publication date.
Perplexity says a model scores page blocks as content or boilerplate to build the Markdown. Highlights keep the page’s original wording rather than summarizing it.
Pricing, limits and parameters
The table below collects the figures Perplexity publishes in its pricing page, the quickstart and the rate limits page.
| Item | Official detail |
|---|---|
| Endpoint | POST https://api.perplexity.ai/v1/context |
| Price | $1.00 per 1,000 fetched URLs ($0.001 per URL) |
| What is billed | URLs with status ok or not_modified, whatever formats you request; failed URLs are free |
| Criteria scoring | Extra Decisions API input tokens (page text plus questions) per scored page |
| URLs per request | Tier 0: 10; Tiers 1–3: 15; Tiers 4–5: 25; never more than 50 |
| Requests per second | Tier 0: 1; Tiers 1–3: 3; Tiers 4–5: 5 |
| Formats | markdown (default), html, links, highlights; [] returns metadata only |
| Default cache age | max_age_seconds 172800 (two days); maximum 63072000 (two years) |
| Timeout | timeout_ms default 30000; range 1000–110000 (95000 with criteria) |
| SDKs | perplexityai 0.48.0+ (Python), @perplexity-ai/perplexity_ai 0.43.0+ (TypeScript) |
Each request counts once against your requests-per-second limit, whatever its URL count. Each successful response reports billed URLs in usage.fetched_urls and a list-price cost in usage.cost.total_cost, which Perplexity notes is not the invoiced amount.
How to make your first request
The quickstart lays out a short path from setup to a working call:
- Install the SDK with
pip install perplexityaiornpm install @perplexity-ai/perplexity_ai, using the minimum versions listed above. - Set your key in the
PERPLEXITY_API_KEYenvironment variable. Perplexity warns against printing the key, even partially, because it can end up in shell history or agent transcripts. - Call
client.context.create(urls=[...])in Python or TypeScript, or send a JSON body with aurlsarray to the endpoint with cURL. - Add
formatsif you need more than Markdown. For highlights, include"highlights"and ahighlightsobject with aquery(1 to 1,024 characters) and an optionalmax_tokens_per_url(1 to 4,096, default 1,024). - Use a result’s content only when
status.typeisok.
One highlights query applies to every URL in a request, so group URLs by question.
Freshness, conditional requests and timeouts
By default, the API returns a stored copy of a page fetched in the last two days and fetches live otherwise.
- Always live: set
max_age_secondsto0for prices, scores and breaking news. - Cache only: set
cache_onlytotrueto never trigger a live fetch. URLs without a recent copy returnno_content. - Change checks: send an earlier
metadata.last_modifiedvalue asif_modified_since, with one URL andmax_age_secondsat0. Unchanged pages returnnot_modified, billed likeok.
URLs are fetched in parallel, so one slow page does not consume the others’ time. A page that runs out of time returns crawl_timeout. The documented approach is to raise timeout_ms and retry only the timed-out URLs.
Scoring pages with criteria
The criteria guide lets you attach 1 to 5 yes-or-no questions to a request. A decision model reads each fetched page and returns a probability from 0 to 1 in criteria.<id>.noul. Perplexity’s main example asks whether a page tries to instruct an AI model, a screen for prompt injection.
Each question uses the Decisions API noul format, with required type and instructions fields (up to 1,000 characters) and optional true and false definitions (up to 500 characters each). There is no threshold field. Scoring never filters or reorders results, so your code must compare scores to its own cutoff.
Scoring tokens are billed at Decisions API rates, which the pricing page lists as $0.02 per million input tokens for pplx-decider-v1.3 and $0.01 for pplx-decider-flash-v1.3. The criteria page does not say which model scores pages. For background on these models, see our Perplexity Decider v1.3 guide and the Perplexity Decisions API guide. Our Granite 4.1 LLMON guide covers another approach to prompt injection defense.
Context API vs. Search API and Agent API
Perplexity’s API overview positions the Context API next to its other web products. Official descriptions and prices:
| API | Starts from | Returns | Price |
|---|---|---|---|
| Context API | URLs you already have | Markdown, HTML, links, highlights, metadata per URL | $1.00 per 1,000 fetched URLs |
| Search API | A query | Ranked results with extracted page text in snippet |
$5.00 per 1,000 requests ($1.00 with Fast Search) |
| Agent API | A prompt | A finished answer with citations from a hosted model | Per-token, by model |
A common pattern is to find URLs with Search, read them with Context, then pass the content to your own model. If you want Perplexity to handle the whole loop, our Perplexity Agent API guide covers the hosted option. To track page changes over time instead, see the Perplexity Monitor API guide.
Against outside providers, Perplexity says it tested the Context API against Firecrawl, Exa, Parallel, Keenable and Context.dev on URLs sampled from real agent fetch requests, scored by a separate judge model. Its developer account reported 92.3% usable content, 87.9% fact recall and 80.3% content precision. These are Perplexity’s own figures and have not been independently verified.
Limitations and tips
- Check every status. A request returns HTTP 200 even when URLs fail. Failure types include
blocked,bot_challenge,crawl_failed,no_textandinternal_error. - Know the request limits. Bodies over 512 KiB or too many URLs return
400. Rate limit errors return429withRetry-After. - Criteria add time. Scoring may add up to 15 seconds, and pages that fail scoring return
criteria_errorinstead of scores.
Frequently asked questions
What is the Perplexity Context API?
It is a developer endpoint, POST https://api.perplexity.ai/v1/context, that takes a batch of URLs you already have and returns each page as Markdown, HTML, a list of links or query-relevant highlights, plus page metadata. Perplexity announced it in a blog post dated November 17, 2026.
How much does the Perplexity Context API cost?
Perplexity lists $1.00 per 1,000 fetched URLs, or $0.001 per URL. You pay only for URLs whose status is ok or not_modified. Failed URLs are free. Adding criteria questions also bills Decisions API input tokens for each scored page.
How many URLs can one Context API request include?
It depends on your usage tier: 10 URLs per request on Tier 0, 15 on Tiers 1 to 3 and 25 on Tiers 4 and 5. Perplexity says a raised limit can go up to 50, and no request can carry more than 50 URLs.
Does the Context API return cached or live pages?
By default it returns a stored copy fetched in the last two days and fetches the page live otherwise. Set max_age_seconds to 0 to always fetch live, or set cache_only to true to use only stored copies.
How is the Context API different from the Perplexity Search API?
The Search API finds pages for a query and returns ranked results with extracted snippets, billed per request. The Context API starts from URLs you already have and returns full page content or highlights, billed per successfully fetched URL.
Sources
- Perplexity Docs: Context API quickstart
- Perplexity Docs: Score pages with criteria
- Perplexity Docs: Pricing
- Perplexity Docs: Rate limits and usage tiers
- Perplexity Docs: API overview
Image: Perplexity AI logo, public domain, via Wikimedia Commons. Perplexity is a trademark of Perplexity AI, Inc.