Perplexity Context API: Power-User Guide to Pricing, Freshness and Criteria

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

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:

  1. Install the SDK with pip install perplexityai or npm install @perplexity-ai/perplexity_ai, using the minimum versions listed above.
  2. Set your key in the PERPLEXITY_API_KEY environment variable. Perplexity warns against printing the key, even partially, because it can end up in shell history or agent transcripts.
  3. Call client.context.create(urls=[...]) in Python or TypeScript, or send a JSON body with a urls array to the endpoint with cURL.
  4. Add formats if you need more than Markdown. For highlights, include "highlights" and a highlights object with a query (1 to 1,024 characters) and an optional max_tokens_per_url (1 to 4,096, default 1,024).
  5. Use a result’s content only when status.type is ok.

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_seconds to 0 for prices, scores and breaking news.
  • Cache only: set cache_only to true to never trigger a live fetch. URLs without a recent copy return no_content.
  • Change checks: send an earlier metadata.last_modified value as if_modified_since, with one URL and max_age_seconds at 0. Unchanged pages return not_modified, billed like ok.

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_text and internal_error.
  • Know the request limits. Bodies over 512 KiB or too many URLs return 400. Rate limit errors return 429 with Retry-After.
  • Criteria add time. Scoring may add up to 15 seconds, and pages that fail scoring return criteria_error instead 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

Image: Perplexity AI logo, public domain, via Wikimedia Commons. Perplexity is a trademark of Perplexity AI, Inc.

Related answers

Leave a Comment