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

> Fetch Markdown, HTML, links, highlights, and page metadata from URLs you already have.

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

You can also [try the Context API in the interactive Playground](https://console.perplexity.ai/project/playground/context).

## Installation

Install the SDK for your language. The Context API needs `perplexityai` 0.48.0 or later, or `@perplexity-ai/perplexity_ai` 0.43.0 or later.

```bash Python theme={null}
pip install perplexityai
```

```bash TypeScript theme={null}
npm install @perplexity-ai/perplexity_ai
```

## Authentication

Set your API key as an environment variable. The SDKs read it automatically:

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

## Basic Usage

Send the URLs to `POST https://api.perplexity.ai/v1/context`. Use a result's content only when its `status.type` is `ok`. The [API reference](https://docs.perplexity.ai/api-reference/context-post.md) lists every field.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.context.create(urls=["https://example.com"])

for result in response.results:
    if result.status.type == "ok":
        print(result.markdown)
    else:
        print(f"{result.url}: {result.status.type}")
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.context.create({ urls: ['https://example.com'] });

for (const result of response.results) {
  if (result.status.type === 'ok') {
    console.log(result.markdown);
  } else {
    console.log(`${result.url}: ${result.status.type}`);
  }
}
```

```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://example.com"]
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "e04b7e25-e753-4568-a5aa-ed8fc8afcd8d",
>   "results": [
>     {
>       "markdown": "Example Domain\nThis domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.",
>       "metadata": {
>         "content_type": "text/html; charset=utf-8",
>         "fetched_at": "2026-11-15T16:48:53Z",
>         "language": "en",
>         "origin": "cached",
>         "source_url": "https://example.com/",
>         "title": "Example Domain",
>         "viewport": "width=device-width,initial-scale=1"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://example.com"
>     }
>   ]
> }
> ```

## Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `urls` | array\[string] | - | Required. `http` or `https` URLs, from 1 to your [usage tier](#rate-limits)'s limit of 10, 15, or 25. A raised limit can go up to 50. |
| `formats` | array\[string] | `["markdown"]` | Any of `markdown`, `html`, `links`, and `highlights`. `[]` returns metadata only. See [Output Formats](#output-formats). |
| `highlights` | object | - | `query` (required, 1 to 1024 characters) and `max_tokens_per_url` (maximum length of each page's highlights in tokens, `1` to `4096`, default `1024`). Required when `formats` includes `highlights`, and allowed only then. See [Output Formats](#output-formats). |
| `max_age_seconds` | integer | `172800` | Maximum age of a stored copy, `0` to `63072000` (two years). `0` always fetches the page live. See [Freshness Control](#freshness-control). |
| `cache_only` | boolean | `false` | Return only stored copies and never fetch live. See [Stored Copies Only](#stored-copies-only). |
| `if_modified_since` | string | - | Return content only if the page changed after this time. See [Conditional Requests](#conditional-requests). |
| `timeout_ms` | integer | `30000` | Fetch time budget for each URL, `1000` to `110000`. See [Timeouts](#timeouts). |

## Output Formats

Use `formats` 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`.

| Format | Field | What you get |
| - | - | - |
| `"markdown"` (default) | `markdown` | The page content as Markdown. |
| `"html"` | `html` | The page's HTML. Left out if the page isn't HTML, such as a PDF. |
| `"links"` | `links` | The page's links as absolute URLs, without duplicates, in page order. `[]` if the page has no links. |
| `"highlights"` | `highlights` | The passages of the page most relevant to `highlights.query`, as one string. Left out if no passage matches. |

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.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.context.create(
    urls=["https://info.cern.ch/hypertext/WWW/TheProject.html"],
    formats=["markdown", "html", "links", "highlights"],
    highlights={
        "query": "What is the World Wide Web project?",
        "max_tokens_per_url": 128,
    },
)

result = response.results[0]
print(result.highlights)
print(result.links)
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.context.create({
  urls: ['https://info.cern.ch/hypertext/WWW/TheProject.html'],
  formats: ['markdown', 'html', 'links', 'highlights'],
  highlights: {
    query: 'What is the World Wide Web project?',
    max_tokens_per_url: 128,
  },
});

const result = response.results[0];
console.log(result.highlights);
console.log(result.links);
```

```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": ["markdown", "html", "links", "highlights"],
    "highlights": {
      "query": "What is the World Wide Web project?",
      "max_tokens_per_url": 128
    }
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "1f41bd6e-2f35-462b-aa0a-cbd19b8a3fd7",
>   "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.\n...\nPointers to the world's online information, subjects , W3 servers, etc.\n...\nIf you would like to support the web..",
>       "html": "<HEADER>\n<TITLE>The World Wide Web project</TITLE>\n<NEXTID N=\"55\">\n</HEADER>\n<BODY>\n<H1>World Wide Web</H1>The WorldWideWeb (W3) is a wide-area<A\nNAME=0 HREF=\"WhatIs.html\">\nhypermedia</A> information retrieval\ninitiative aiming to give universal\naccess 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"
>       ],
>       "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...",
>       "metadata": {
>         "content_type": "text/html",
>         "fetched_at": "2026-11-15T23:38:37Z",
>         "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"
>     }
>   ]
> }
> ```

### Metadata

A result with content has `metadata`, 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.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.context.create(urls=["https://www.python.org"], formats=[])

print(response.results[0].metadata.to_json())
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.context.create({ urls: ['https://www.python.org'], formats: [] });

console.log(response.results[0].metadata);
```

```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://www.python.org"],
    "formats": []
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "69ed0d76-6d1b-4ae9-a579-3456826e6426",
>   "results": [
>     {
>       "metadata": {
>         "apple-mobile-web-app-capable": "yes",
>         "apple-mobile-web-app-status-bar-style": "black",
>         "apple-mobile-web-app-title": "Python.org",
>         "application-name": "Python.org",
>         "content_type": "text/html; charset=utf-8",
>         "description": "The official home of the Python Programming Language",
>         "fetched_at": "2026-11-16T19:17:41Z",
>         "format-detection": "telephone=no",
>         "handheldfriendly": "True",
>         "keywords": "Python programming language object oriented web free open source software license documentation download community",
>         "language": "en",
>         "msapplication-navbutton-color": "#3673a5",
>         "msapplication-tilecolor": "#3673a5",
>         "msapplication-tileimage": "/static/metro-icon-144x144.png",
>         "og:description": "The official home of the Python Programming Language",
>         "og:image": "https://www.python.org/static/opengraph-icon-200x200.png",
>         "og:image:secure_url": "https://www.python.org/static/opengraph-icon-200x200.png",
>         "og:site_name": "Python.org",
>         "og:title": "Welcome to Python.org",
>         "og:type": "website",
>         "og:url": "https://www.python.org/",
>         "origin": "cached",
>         "published_date": "2026-11-13",
>         "source_url": "https://www.python.org/",
>         "title": "Welcome to Python.org",
>         "viewport": "width=device-width, initial-scale=1.0"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://www.python.org"
>     }
>   ]
> }
> ```

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

Use `max_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.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Accept a copy fetched within the last week
response = client.context.create(urls=["https://example.com"], max_age_seconds=604800)

metadata = response.results[0].metadata
print(metadata.origin, metadata.fetched_at)
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

// Accept a copy fetched within the last week
const response = await client.context.create({ urls: ['https://example.com'], max_age_seconds: 604800 });

const metadata = response.results[0].metadata;
console.log(metadata?.origin, metadata?.fetched_at);
```

```bash cURL theme={null}
# Accept a copy fetched within the last week
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://example.com"],
    "max_age_seconds": 604800
  }' | jq
```

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Always fetch the current version, for prices, scores, and breaking news
response = client.context.create(urls=["https://example.com"], max_age_seconds=0)

metadata = response.results[0].metadata
print(metadata.origin, metadata.fetched_at)
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

// Always fetch the current version, for prices, scores, and breaking news
const response = await client.context.create({ urls: ['https://example.com'], max_age_seconds: 0 });

const metadata = response.results[0].metadata;
console.log(metadata?.origin, metadata?.fetched_at);
```

```bash cURL theme={null}
# Always fetch the current version, for prices, scores, and breaking news
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://example.com"],
    "max_age_seconds": 0
  }' | jq
```

### Stored Copies Only

Set `cache_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.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.context.create(
    urls=["https://www.python.org", "https://example.com/a-page-that-is-not-stored"],
    formats=[],
    cache_only=True,
    max_age_seconds=604800,
)

for result in response.results:
    print(result.url, result.status.type)
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.context.create({
  urls: ['https://www.python.org', 'https://example.com/a-page-that-is-not-stored'],
  formats: [],
  cache_only: true,
  max_age_seconds: 604800,
});

for (const result of response.results) {
  console.log(result.url, result.status.type);
}
```

```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://www.python.org", "https://example.com/a-page-that-is-not-stored"],
    "formats": [],
    "cache_only": true,
    "max_age_seconds": 604800
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "0d3914c8-794f-4145-869f-54866c1448c6",
>   "results": [
>     {
>       "metadata": {
>         "apple-mobile-web-app-capable": "yes",
>         "apple-mobile-web-app-status-bar-style": "black",
>         "apple-mobile-web-app-title": "Python.org",
>         "application-name": "Python.org",
>         "content_type": "text/html; charset=utf-8",
>         "description": "The official home of the Python Programming Language",
>         "fetched_at": "2026-11-16T19:17:41Z",
>         "format-detection": "telephone=no",
>         "handheldfriendly": "True",
>         "keywords": "Python programming language object oriented web free open source software license documentation download community",
>         "language": "en",
>         "msapplication-navbutton-color": "#3673a5",
>         "msapplication-tilecolor": "#3673a5",
>         "msapplication-tileimage": "/static/metro-icon-144x144.png",
>         "og:description": "The official home of the Python Programming Language",
>         "og:image": "https://www.python.org/static/opengraph-icon-200x200.png",
>         "og:image:secure_url": "https://www.python.org/static/opengraph-icon-200x200.png",
>         "og:site_name": "Python.org",
>         "og:title": "Welcome to Python.org",
>         "og:type": "website",
>         "og:url": "https://www.python.org/",
>         "origin": "cached",
>         "published_date": "2026-11-13",
>         "source_url": "https://www.python.org/",
>         "title": "Welcome to Python.org",
>         "viewport": "width=device-width, initial-scale=1.0"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://www.python.org"
>     },
>     {
>       "status": {
>         "message": "No content was found for this URL.",
>         "type": "no_content"
>       },
>       "url": "https://example.com/a-page-that-is-not-stored"
>     }
>   ]
> }
> ```

### Conditional Requests

To check whether a page changed since you last read it, send the `metadata.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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/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.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.context.create(
    urls=["https://info.cern.ch/hypertext/WWW/TheProject.html"],
    max_age_seconds=0,
    if_modified_since="Thu, 03 Dec 1992 08:37:20 GMT",
)

print(response.results[0].status.type)
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.context.create({
  urls: ['https://info.cern.ch/hypertext/WWW/TheProject.html'],
  max_age_seconds: 0,
  if_modified_since: 'Thu, 03 Dec 1992 08:37:20 GMT',
});

console.log(response.results[0].status.type);
```

```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"],
    "max_age_seconds": 0,
    "if_modified_since": "Thu, 03 Dec 1992 08:37:20 GMT"
  }' | jq
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "fe79d1ab-c653-483b-8cc3-f3d8cf5b92bd",
>   "results": [
>     {
>       "metadata": {
>         "fetched_at": "2026-11-16T20:55:03Z",
>         "last_modified": "Thu, 03 Dec 1992 08:37:20 GMT",
>         "origin": "live",
>         "source_url": "https://info.cern.ch/hypertext/WWW/TheProject.html"
>       },
>       "status": {
>         "status_code": 304,
>         "type": "not_modified"
>       },
>       "url": "https://info.cern.ch/hypertext/WWW/TheProject.html"
>     }
>   ]
> }
> ```

## 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](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md#context-api-rate-limits) sets that limit and the most URLs one request can carry:

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

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.

> [!NOTE]
>
> If you need higher limits, [request an increase](https://perplexity.typeform.com/to/yctmfyVT).

## Error Handling

A request can fail as a whole with an HTTP error, or single URLs can fail inside a `200` response, as shown by each result's `status`.

### Request Errors

When the whole request fails, the API returns an `error` 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, a `400` can mean zero URLs or more than your tier allows, a request body over 512 KiB, a `null` value, an unknown parameter or format, or parameters that can't be combined.
* `401` or `403`: check your API key, credit balance, and your organization's API access settings.
* `429`: wait for the number of seconds in the `Retry-After` header, then retry. See [Rate Limits](#rate-limits).
* `500`, `502`, `503`, or `504`: you can retry the request. No results are returned, including ones that finished.

### Per-URL Errors

A request returns HTTP `200` 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.

| `status.type` | Meaning |
| - | - |
| `ok` | Content returned. |
| `not_modified` | Unchanged since `if_modified_since`. Keep your earlier content. |
| `invalid_url` | Not an absolute `http` or `https` URL. |
| `blocked` | The URL is blocked and was not fetched. |
| `bot_challenge` | The site answered with a bot challenge. |
| `crawl_failed` | The fetch failed. `status_code` has the site's status when it answered. |
| `crawl_timeout` | Fetching the page timed out. See [Timeouts](#timeouts). |
| `no_text` | The page has no text, and `formats` has `markdown`. |
| `no_content` | No content was found for the URL, for example with `cache_only`. |
| `internal_error` | The URL could not be read. Retry later. |

> [accordion] 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.
>
> ```python Python theme={null}
> from perplexity import Perplexity
>
> client = Perplexity()
>
> response = client.context.create(
>     urls=["https://example.com", "https://example.com/this-page-does-not-exist", "not-a-url"],
> )
>
> for result in response.results:
>     if result.status.type != "ok":
>         print(result.url, result.status.type, result.status.message)
> ```
>
> ```typescript TypeScript theme={null}
> import Perplexity from '@perplexity-ai/perplexity_ai';
>
> const client = new Perplexity();
>
> const response = await client.context.create({
>   urls: ['https://example.com', 'https://example.com/this-page-does-not-exist', 'not-a-url'],
> });
>
> for (const result of response.results) {
>   if (result.status.type !== 'ok') {
>     console.log(result.url, result.status.type, result.status.message);
>   }
> }
> ```
>
> ```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://example.com", "https://example.com/this-page-does-not-exist", "not-a-url"]
>   }' | jq
> ```
>
> ```json Response theme={null}
> {
>   "request_id": "b90381bf-4a49-4a40-a4e7-1d4ba740bb37",
>   "results": [
>     {
>       "markdown": "Example Domain\nThis domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.",
>       "metadata": {
>         "content_type": "text/html; charset=utf-8",
>         "fetched_at": "2026-11-17T14:31:29Z",
>         "language": "en",
>         "origin": "cached",
>         "source_url": "https://example.com/",
>         "title": "Example Domain",
>         "viewport": "width=device-width,initial-scale=1"
>       },
>       "status": {
>         "status_code": 200,
>         "type": "ok"
>       },
>       "url": "https://example.com"
>     },
>     {
>       "status": {
>         "message": "The page could not be fetched.",
>         "status_code": 404,
>         "type": "crawl_failed"
>       },
>       "url": "https://example.com/this-page-does-not-exist"
>     },
>     {
>       "status": {
>         "message": "The URL is invalid.",
>         "type": "invalid_url"
>       },
>       "url": "not-a-url"
>     }
>   ]
> }
> ```

## Pricing

See [Context API pricing](https://docs.perplexity.ai/docs/getting-started/pricing.md#context-api-pricing) for rates and billable units. Use the [pricing calculator](https://docs.perplexity.ai/docs/getting-started/pricing.md?calc=context#estimate-your-cost) to estimate costs for your usage.

Each successful 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.

## 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, query-relevant excerpts

> [card] [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart.md)
>
> Let a model search and read the web for you, with citations
