Overview
The Context API returns the content of web pages you already have URLs for, ready for LLMs and agents. Send a batch of URLs in one request. 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. You choose how fresh the content is: read from cache or force a live fetch. To find pages for a query, use the Search API. For a generated answer with citations, use the Agent API. You can also try the Context API in the interactive Playground.Installation
Install the SDK for your language. The Context API needsperplexityai 0.48.0 or later, or @perplexity-ai/perplexity_ai 0.43.0 or later.
Authentication
Set your API key as an environment variable. The SDKs read it automatically:- macOS/Linux
- Windows
- macOS/Linux
- Windows
Basic Usage
Send the URLs toPOST https://api.perplexity.ai/v1/context. Use a result’s content only when its status.type is ok. The API reference lists every field.
Response
Response
Parameters
Output Formats
Useformats to choose what each result includes besides metadata. Only the formats you request appear, and any other value in formats returns 400 with error type unsupported_format.
To get highlights, add
"highlights" to formats and send a highlights object with your query. Use them when your model needs only the parts of a page that answer a question. One query applies to every URL in the request. Highlights work alone or together with the other formats.
Response
Response
Metadata
A result with content hasmetadata, whatever formats asks for. To get only metadata, send "formats": [].
metadata always has source_url. It can also have title, description, language, author, published_date, 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 or viewport: a string, or an array in page order if the page repeats the tag.
Response
Response
Freshness Control
By default, the Context API returns a stored copy of a page if it was fetched in the last two days, and fetches the page live otherwise. A stored copy is returned without contacting the site, so that result doesn’t wait on a live fetch and can’t fail because the site is slow or down. A live fetch returns the page as it is now. Usemax_age_seconds to choose how old a stored copy can be. A higher value lets more pages come from stored copies, and 0 always fetches live.
metadata.origin shows where a result came from: cached for a stored copy, or live for a page fetched for this request. metadata.fetched_at is when that content was fetched.
Stored Copies Only
Setcache_only to true to answer only from stored copies no older than max_age_seconds, without any live fetch. A URL with no stored copy that recent comes back with status.type no_content. cache_only needs max_age_seconds above 0; leave it out to use the two-day default.
Response
Response
Conditional Requests
To check whether a page changed since you last read it, send themetadata.last_modified value from your earlier response as if_modified_since. A conditional request takes exactly one URL and needs max_age_seconds set to 0. metadata.last_modified is present only when the site sends a Last-Modified header.
if_modified_since must be an HTTP date in GMT, in the format of the If-Modified-Since header, such as Thu, 03 Dec 1992 08:37:20 GMT. metadata.last_modified is already in that format. Any other date format returns 400.
If the page hasn’t changed, its result has status.type not_modified and metadata, but no markdown, html, links, or highlights, so keep the content from your earlier request. If the page changed, or the site doesn’t support conditional requests, the result is a normal ok result with content. A not_modified result is billed like an ok result.
Response
Response
Timeouts
timeout_ms is how long each URL can take to fetch. 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 doesn’t finish in time comes back with status.type crawl_timeout, and the rest keep their content.
For slow pages, raise timeout_ms, and retry only the URLs that came back with crawl_timeout.
Rate Limits
Each request counts as one unit against your organization’s requests-per-second limit, whatever its URL count. Your usage tier sets that limit and the most URLs one request can carry:
Over the rate limit, the request fails with HTTP
429 and error type request_rate_limit_exceeded. Wait for the number of seconds in the Retry-After header, then retry.
A request with more URLs than your tier allows fails with 400, error type invalid_request, and param urls, without counting against your rate limit. Split it into smaller requests.
If you need higher limits, request an increase.
Error Handling
A request can fail as a whole with an HTTP error, or single URLs can fail inside a200 response, as shown by each result’s status.
Request Errors
When the whole request fails, the API returns anerror object with message, type, and code, and no results. Errors the Context API returns itself also have request_id, and request errors about one field have param.
400: fix the request, because sending it again unchanged fails the same way. For example, a400can mean zero URLs or more than your tier allows, a request body over 512 KiB, anullvalue, an unknown parameter or format, or parameters that can’t be combined.401or403: check your API key, credit balance, and your organization’s API access settings.429: wait for the number of seconds in theRetry-Afterheader, then retry. See Rate Limits.500,502,503, or504: you can retry the request. No results are returned, including ones that finished.
Per-URL Errors
A request returns HTTP200 even when some or all URLs fail, so check status.type on each 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, present on ok, not_modified, bot_challenge, and crawl_failed when the site answered.
Example: a request with failed URLs
Example: a request with failed URLs
The first URL returns content, the site answers
404 for the second, and the third is not a URL.Response
Pricing
See Context API pricing for rates and billable units. Use the pricing calculator to estimate costs for your usage. Each successful response has ausage 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.
Next Steps
API Reference
Request and response schemas for POST /v1/context
Search API
Find URLs for a query and get ranked, query-relevant excerpts
Agent API
Let a model search and read the web for you, with citations