Overview
The Context API returns the content of web pages you already have URLs for. Send a batch of URLs in one request and get one result per URL, in the order you sent them. Each result can include the page as Markdown, its HTML, its links, the passages most relevant to a query you send, and page metadata such as title, language, and publication date. The Context API returns extracted page content and metadata. It does not search the web, rank pages, or generate answers. To find pages for a query, use the Search API. For an answer with citations, use the Agent API.Authentication
Set your API key as an environment variable:- macOS/Linux
- Windows
- macOS/Linux
- Windows
Authorization header.
Basic Usage
Send your URLs toPOST https://api.perplexity.ai/v1/context. By default, each result has the page as Markdown and its metadata. Use a result’s content only when its status.type is ok.
The Perplexity SDKs don’t have a Context API method, so these examples call the endpoint over HTTP. The Python example uses httpx (pip install httpx).
Response
Response
markdown value above is shortened. The API reference lists every field.
Parameters
Any other parameter returns
400 with error type unsupported_param. A null value anywhere in the body returns 400.
Output formats
Useformats to choose what each ok result includes besides metadata. Only the formats you request appear.
An unknown value in
formats returns 400 with error type unsupported_format.
Highlights
To get only the parts of a page that answer a question, addhighlights to formats and send a highlights object with your query. One query applies to every URL in the request. max_tokens_per_url caps the length of each page’s highlights in tokens.
cURL
Response
Response
Metadata
Everyok and not_modified result has metadata, whatever formats asks for. Send "formats": [] to get metadata only. A metadata-only result is billed like any other ok result.
metadata.source_url is always present. It is the URL the content came from after normalization and redirects, so it can differ from url. These fields appear when the page has a value for them: title, description, language, author, published_date (YYYY-MM-DD), content_type, origin, fetched_at, and last_modified. Every other meta tag in the page’s <head> appears under its lowercased name, such as og:title: a string, or an array in page order when the page repeats the tag.
Freshness
The Context API can return a stored copy of a page or fetch it live.metadata.origin is cached for a stored copy and live for a page fetched for your request. metadata.fetched_at is when the returned content was fetched.
max_age_seconds: the oldest stored copy you accept. The default is172800(two days). A URL without a stored copy that recent is fetched live.0always fetches live.cache_only: set totrueto return only stored copies no older thanmax_age_seconds, without any live fetch. A URL without one returnsstatus.typeno_content. It requiresmax_age_secondsabove0.snapshot_as_of: an RFC 3339 time with a time zone, such as2026-11-01T00:00:00Z, that is not in the future and not more than 90 days ago. Each URL returns as stored at or before that time, orno_contentif no copy exists. It never fetches live, and you can’t combine it withmax_age_seconds,cache_only, orif_modified_since.if_modified_since: themetadata.last_modifiedvalue from an earlier response, an HTTP date such asThu, 03 Dec 1992 08:37:20 GMT. The request must have exactly one URL andmax_age_secondsset to0. If the page has not changed, the result hasstatus.typenot_modifiedandmetadatabut no content, so keep the content you already have.metadata.last_modifiedappears only when the site sends aLast-Modifiedheader.
cURL
Timeouts
timeout_ms is the time budget for fetching each URL. URLs are fetched in parallel, so one slow page doesn’t use up the time of the others. The default is 30000 and the range is 1000 to 110000. A URL that is not fetched within the budget returns status.type crawl_timeout, and URLs that finished keep their content. For slow pages, raise timeout_ms and retry only the URLs that returned crawl_timeout or crawl_failed.
If the whole request runs longer than timeout_ms plus 10 seconds, it fails with 504 and error type gateway_timeout, and no results are returned.
Check each result
A request returns HTTP200 even when some or all URLs fail, so check status.type on every result before you use its content. A failed result has only url and status, with a fixed status.message. status.status_code is the site’s own HTTP status. It appears on ok, not_modified, bot_challenge, and crawl_failed results when the site answered.
This request sends a page that exists, a page that doesn’t, and a string that isn’t a URL:
cURL
Response
Response
ok result is billed, so usage.fetched_urls is 1.
Limits
Your organization’s usage tier sets how many requests you can send per second and how many URLs one request can carry. A request counts once against the per-second limit, whatever its URL count.
No request can carry more than 50 URLs. A request with more URLs than your tier allows fails with
400 and param urls, before it counts against your rate limit. Split it into smaller requests.
Over the rate limit, the request fails with 429 and error type request_rate_limit_exceeded. Wait for the number of seconds in the Retry-After header, then retry. Successful responses that counted against your rate limit include x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used, and x-ratelimit-reset (Unix seconds) headers.
If you need higher limits, request an increase.
Pricing
The Context API costs $1.00 per 1,000 URLs ($0.001 per URL). You pay for each URL whose result hasstatus.type ok or not_modified, whatever formats asks for. Failed URLs are not billed. Each response has a usage object: usage.fetched_urls is the number of billed URLs, and usage.cost.total_cost is their cost in USD at list price, which is not the amount charged. See Context API pricing.
Errors
When the whole request fails, the response has anerror object with message, type, and code, and no results. Errors about one field also have param, and errors returned by the Context API itself have request_id.
A value outside a parameter’s range returns
400 with invalid_request, the parameter in param, and a message such as timeout_ms must be at least 1000. For 401, check your API key and credit balance: insufficient_quota means the account is out of credits. For 403, check your organization’s API access settings. On 500, 502, 503, and 504, no results are returned and you can retry.
Next steps
API reference
Request and response schemas for
POST /v1/contextSearch API
Find URLs for a query and get ranked results