> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context API quickstart

> Get Markdown, HTML, links, query highlights, and page metadata for URLs you already have.

## 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](https://docs.perplexity.ai/docs/search/quickstart.md). For an answer with citations, use the [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart.md).

## Authentication

Set your API key as an environment variable:

> [tab] macOS/Linux
>
> ```bash theme={null}
> export PERPLEXITY_API_KEY="your_api_key_here"
> ```

> [tab] Windows
>
> ```powershell theme={null}
> setx PERPLEXITY_API_KEY "your_api_key_here"
> ```

Confirm the key is set without printing it:

> [tab] macOS/Linux
>
> ```bash theme={null}
> test -n "$PERPLEXITY_API_KEY" && echo "PERPLEXITY_API_KEY is set" || echo "PERPLEXITY_API_KEY is not set"
> ```

> [tab] Windows
>
> ```powershell theme={null}
> if ($env:PERPLEXITY_API_KEY) { "PERPLEXITY_API_KEY is set" } else { "PERPLEXITY_API_KEY is not set" }
> ```

> [!WARNING]
>
> 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`](https://www.python-httpx.org) (`pip install httpx`).

```python Python theme={null}
import os
import httpx

response = httpx.post(
    "https://api.perplexity.ai/v1/context",
    headers={"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"},
    json={"urls": ["https://info.cern.ch/hypertext/WWW/TheProject.html"]},
    timeout=90,
)
response.raise_for_status()
body = response.json()

for result in body["results"]:
    if result["status"]["type"] == "ok":
        print(result["metadata"].get("title"))
        print(result["markdown"][:500])
    else:
        print(result["url"], result["status"]["type"], result["status"].get("message"))

print("Billed URLs:", body["usage"]["fetched_urls"])
```

```typescript Typescript theme={null}
const response = await fetch("https://api.perplexity.ai/v1/context", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://info.cern.ch/hypertext/WWW/TheProject.html"],
  }),
});
if (!response.ok) {
  throw new Error(`Context API error ${response.status}: ${await response.text()}`);
}
const body = await response.json();

for (const result of body.results) {
  if (result.status.type === "ok") {
    console.log(result.metadata.title);
    console.log(result.markdown.slice(0, 500));
  } else {
    console.log(result.url, result.status.type, result.status.message);
  }
}

console.log("Billed URLs:", body.usage.fetched_urls);
```

```bash cURL theme={null}
curl --fail-with-body --max-time 90 https://api.perplexity.ai/v1/context \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://info.cern.ch/hypertext/WWW/TheProject.html"]
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "275fdeba-bc88-466a-a029-48429cf97ff6",
>   "results": [
>     {
>       "markdown": "The World Wide Web project\n\n# World Wide Web\nThe WorldWideWeb (W3) is a wide-area hypermedia information retrieval initiative aiming to give universal access to a large universe of documents.\n\nEverything there is online about\nW3 is linked directly or indirectly\nto this document, including an executive summary of the project, Mailing lists , Policy , November's W3 news , Frequently Asked Questions .\n\n- **What's out there?**\n  Pointers to the world's online information, subjects , W3 servers, etc.\n- **Help**\n  on the browser you are using\n...",
>       "metadata": {
>         "content_type": "text/html",
>         "fetched_at": "2026-11-16T23:55:18Z",
>         "origin": "cached",
>         "source_url": "https://info.cern.ch/hypertext/WWW/TheProject.html",
>         "title": "The World Wide Web project"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://info.cern.ch/hypertext/WWW/TheProject.html"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

The `markdown` value above is shortened. The [API reference](https://docs.perplexity.ai/api-reference/context-post.md) lists every field.

## Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `urls` | array of strings | - | Required. 1 to 50 URLs, and no more than your [usage tier](#limits) allows. A string that is not an absolute `http` or `https` URL does not fail the request: its result has `status.type` `invalid_url`. |
| `formats` | array of strings | `["markdown"]` | Any of `markdown`, `html`, `links`, and `highlights`. `[]` returns metadata only. See [Output formats](#output-formats). |
| `highlights` | object | - | `query` (required, 1 to 1024 characters, with at least one non-whitespace character) and `max_tokens_per_url` (`1` to `4096`, default `1024`). Required when `formats` includes `highlights`, and allowed only then. |
| `max_age_seconds` | integer | `172800` | Maximum age of a stored copy you accept, `0` to `63072000`. `0` always fetches the page live. See [Freshness](#freshness). |
| `cache_only` | boolean | `false` | Return only stored copies and never fetch live. Requires `max_age_seconds` above `0`. |
| `snapshot_as_of` | string | - | An RFC 3339 time with a time zone, such as `2026-11-01T00:00:00Z`. Returns each page as stored at or before that time. See [Freshness](#freshness). |
| `if_modified_since` | string | - | An HTTP date. Returns content only if the page changed after that time. |
| `timeout_ms` | integer | `30000` | Time budget for fetching each URL, in milliseconds, `1000` to `110000`. URLs are fetched in parallel. See [Timeouts](#timeouts). |

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.

| Format | Field | What you get |
| - | - | - |
| `markdown` | `markdown` | The page content as Markdown. |
| `html` | `html` | The page's HTML. Left out for a page that is not HTML, such as a PDF. |
| `links` | `links` | An array of the page's links as URL strings, resolved to absolute URLs, without duplicates, in page order. `[]` for a page without links. |
| `highlights` | `highlights` | The passages of the page most relevant to `highlights.query`, as one string, with passages separated by a line holding an ellipsis (`...` or `…`). Left out when no passage matches. |

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.

```bash cURL theme={null}
curl --fail-with-body --max-time 90 https://api.perplexity.ai/v1/context \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://info.cern.ch/hypertext/WWW/TheProject.html"],
    "formats": ["highlights", "links"],
    "highlights": {
      "query": "What is the WorldWideWeb project?",
      "max_tokens_per_url": 128
    }
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "d2c3f2fd-2d33-4a9f-9d5d-fa7ed62239a9",
>   "results": [
>     {
>       "highlights": "# World Wide Web\nThe WorldWideWeb (W3) is a wide-area hypermedia information retrieval initiative aiming to give universal access to a large universe of documents.",
>       "links": [
>         "https://info.cern.ch/hypertext/WWW/WhatIs.html",
>         "https://info.cern.ch/hypertext/WWW/Summary.html",
>         "https://info.cern.ch/hypertext/WWW/Administration/Mailing/Overview.html",
>         "https://info.cern.ch/hypertext/WWW/Policy.html",
>         "https://info.cern.ch/hypertext/WWW/News/9211.html",
>         "https://info.cern.ch/hypertext/WWW/FAQ/List.html",
>         "https://info.cern.ch/hypertext/DataSources/Top.html",
>         "https://info.cern.ch/hypertext/DataSources/bySubject/Overview.html",
>         "https://info.cern.ch/hypertext/DataSources/WWW/Servers.html",
>         "https://info.cern.ch/hypertext/WWW/Help.html",
>         "https://info.cern.ch/hypertext/WWW/Status.html",
>         "https://info.cern.ch/hypertext/WWW/LineMode/Browser.html",
>         "https://info.cern.ch/hypertext/WWW/Status.html#35",
>         "https://info.cern.ch/hypertext/WWW/NeXT/WorldWideWeb.html",
>         "https://info.cern.ch/hypertext/WWW/Daemon/Overview.html",
>         "https://info.cern.ch/hypertext/WWW/Tools/Overview.html",
>         "https://info.cern.ch/hypertext/WWW/MailRobot/Overview.html",
>         "https://info.cern.ch/hypertext/WWW/Status.html#57",
>         "https://info.cern.ch/hypertext/WWW/Technical.html",
>         "https://info.cern.ch/hypertext/WWW/Bibliography.html",
>         "https://info.cern.ch/hypertext/WWW/People.html",
>         "https://info.cern.ch/hypertext/WWW/History.html",
>         "https://info.cern.ch/hypertext/WWW/Helping.html",
>         "https://info.cern.ch/hypertext/README.html",
>         "https://info.cern.ch/hypertext/WWW/LineMode/Defaults/Distribution.html"
>       ],
>       "metadata": {
>         "content_type": "text/html",
>         "fetched_at": "2026-11-16T23:55:18Z",
>         "origin": "cached",
>         "source_url": "https://info.cern.ch/hypertext/WWW/TheProject.html",
>         "title": "The World Wide Web project"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://info.cern.ch/hypertext/WWW/TheProject.html"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

### 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:

```bash cURL theme={null}
curl --fail-with-body --max-time 90 https://api.perplexity.ai/v1/context \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://info.cern.ch/hypertext/WWW/TheProject.html"],
    "formats": [],
    "max_age_seconds": 604800,
    "cache_only": true
  }' | jq
```

## 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.

| `status.type` | Meaning | `status.message` |
| - | - | - |
| `ok` | Content returned. | - |
| `not_modified` | Unchanged since `if_modified_since`. Keep your earlier content. | - |
| `invalid_url` | Not an absolute `http` or `https` URL. | `The URL is invalid.` |
| `blocked` | The URL is blocked and was not fetched. | `This URL is blocked.` |
| `bot_challenge` | The site answered with a bot challenge. | `The site answered with a bot challenge.` |
| `crawl_failed` | The fetch failed. | `The page could not be fetched.` |
| `crawl_timeout` | The URL was not fetched within `timeout_ms`. | `Fetching the page timed out.` |
| `no_text` | The page has no text, and `formats` includes `markdown`. | `The page has no text.` |
| `no_content` | No content was found for the URL, for example with `cache_only` or `snapshot_as_of`. | `No content was found for this URL.` |
| `internal_error` | The page could not be read. Retry later. | `The page could not be read. Retry later.` |

This request sends a page that exists, a page that doesn't, and a string that isn't a URL:

```bash cURL theme={null}
curl --fail-with-body --max-time 90 https://api.perplexity.ai/v1/context \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://info.cern.ch/hypertext/WWW/TheProject.html",
      "https://info.cern.ch/hypertext/WWW/this-page-does-not-exist.html",
      "not-a-url"
    ],
    "formats": []
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "f434706c-9f46-47f2-9714-369f1ce23c96",
>   "results": [
>     {
>       "metadata": {
>         "content_type": "text/html",
>         "fetched_at": "2026-11-16T23:55:18Z",
>         "origin": "cached",
>         "source_url": "https://info.cern.ch/hypertext/WWW/TheProject.html",
>         "title": "The World Wide Web project"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://info.cern.ch/hypertext/WWW/TheProject.html"
>     },
>     {
>       "status": {
>         "message": "The page could not be fetched.",
>         "status_code": 404,
>         "type": "crawl_failed"
>       },
>       "url": "https://info.cern.ch/hypertext/WWW/this-page-does-not-exist.html"
>     },
>     {
>       "status": {
>         "message": "The URL is invalid.",
>         "type": "invalid_url"
>       },
>       "url": "not-a-url"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

Only the `ok` result is billed, so `usage.fetched_urls` is `1`.

## Limits

Your organization's [usage tier](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md#context-api-limits) 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.

| Tier | Requests per second | URLs per request |
| - | :-: | :-: |
| Tier 0 | 1 | 10 |
| Tiers 1-3 | 3 | 15 |
| Tiers 4-5 | 5 | 25 |

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](https://perplexity.typeform.com/to/yctmfyVT).

## 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](https://docs.perplexity.ai/docs/getting-started/pricing.md#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`.

| HTTP status | `error.type` | `error.message` | Fix |
| - | - | - | - |
| `400` | `invalid_request` | `request body must be a JSON object` | Send a JSON object. |
| `400` | `invalid_request` | `request body is too large` | Keep the body under 512 KiB. |
| `400` | `unsupported_param` | `parameter "<name>" is not supported` | Remove the parameter. |
| `400` | `invalid_request` | `<field> must not be or contain null` | Leave out the field instead of sending `null`. |
| `400` | `invalid_request` | `<field> has an invalid type` | Send the type in [Parameters](#parameters). |
| `400` | `invalid_request` | `urls must contain at least 1 URL` | Send at least one URL. |
| `400` | `invalid_request` | `urls must contain at most 50 URLs` | Split the request. |
| `400` | `invalid_request` | `urls must contain at most <n> URLs for this account` | Split the request to fit your [tier's limit](#limits). |
| `400` | `unsupported_format` | `format "<value>" is not supported` | Use `markdown`, `html`, `links`, or `highlights`. |
| `400` | `invalid_request` | `highlights is required when formats has highlights` | Add a `highlights` object. |
| `400` | `invalid_request` | `formats must have highlights when highlights is set` | Add `highlights` to `formats`. |
| `400` | `invalid_request` | `highlights.query is required` | Send a non-empty query. |
| `400` | `invalid_request` | `highlights.query must contain a non-whitespace character` | Send a query with text in it. |
| `400` | `invalid_request` | `cache_only requires max_age_seconds above 0` | Raise `max_age_seconds` or leave it out. |
| `400` | `invalid_request` | `snapshot_as_of must be an RFC 3339 timestamp with a timezone` | Use a time such as `2026-11-01T00:00:00Z`. |
| `400` | `invalid_request` | `snapshot_as_of must not be in the future` | Use a past time. |
| `400` | `invalid_request` | `snapshot_as_of must not be older than 90 days` | Use a time from the last 90 days. |
| `400` | `invalid_request` | `snapshot_as_of cannot be combined with max_age_seconds or if_modified_since` | Remove one of them. |
| `400` | `invalid_request` | `snapshot_as_of cannot be combined with cache_only` | Remove `cache_only`, even when it is `false`. |
| `400` | `invalid_request` | `if_modified_since requires an IMF-fixdate, one URL, and max_age_seconds=0` | Send one URL, `max_age_seconds: 0`, and an HTTP date. |
| `405` | `invalid_request` | `/v1/context accepts only POST` | Use `POST`. |
| `429` | `request_rate_limit_exceeded` | `Rate limit exceeded, please try again later.` | Wait for `Retry-After` seconds, then retry. |
| `502` | `bad_gateway` | `The content service failed to process the request.` | Retry the request. |
| `504` | `gateway_timeout` | `The request did not complete within timeout_ms.` | Retry the request. |

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

> [card] [API reference](https://docs.perplexity.ai/api-reference/context-post.md)
>
> Request and response schemas for `POST /v1/context`

> [card] [Search API](https://docs.perplexity.ai/docs/search/quickstart.md)
>
> Find URLs for a query and get ranked results
