Skip to main content

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:
Confirm the key is set without printing it:
Never print the key or any part of it. Commands like env, echo $PERPLEXITY_API_KEY, or a prefix or length check leave the key in shell history, logs, and coding-agent transcripts. Read the key from the environment in code and tests, and don’t paste it into fixtures or commit messages.
Send the key as a bearer token in the Authorization header.

Basic Usage

Send your URLs to POST 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).
The 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

Use formats 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, add highlights 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

Metadata

Every ok 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 is 172800 (two days). A URL without a stored copy that recent is fetched live. 0 always fetches live.
  • cache_only: set to true to return only stored copies no older than max_age_seconds, without any live fetch. A URL without one returns status.type no_content. It requires max_age_seconds above 0.
  • snapshot_as_of: an RFC 3339 time with a time zone, such as 2026-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, or no_content if no copy exists. It never fetches live, and you can’t combine it with max_age_seconds, cache_only, or if_modified_since.
  • if_modified_since: the metadata.last_modified value from an earlier response, an HTTP date such as Thu, 03 Dec 1992 08:37:20 GMT. The request must have exactly one URL and max_age_seconds set to 0. If the page has not changed, the result has status.type not_modified and metadata but no content, so keep the content you already have. metadata.last_modified appears only when the site sends a Last-Modified header.
This request accepts stored copies up to a week old and never fetches live:
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 HTTP 200 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
Only the 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 has status.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 an error 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/context

Search API

Find URLs for a query and get ranked results