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

# Formats and freshness

> Choose what each Context API result returns, how old a stored copy can be, and how to handle URLs that fail.

## Output Formats

`formats` chooses what each result includes besides metadata. The default is `["markdown"]`, and only the formats you request appear. An unknown format name returns `400` with error type `unsupported_format`.

| Format | Field | What you get |
| - | - | - |
| `"markdown"` | `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 was returned within `max_tokens_per_url`. |

Highlights need a `highlights` object with your `query`, and `max_tokens_per_url` caps the length of each page's highlights. One query applies to every URL in the request. Use highlights when your model needs only the parts of a page that answer a question.

```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": "83f25555-ed6b-40fa-b0e7-3e46cdc0fa30",
>   "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.<P>\nEverything there is online about\nW3 is linked directly or indirectly\nto this document, including an <A\nNAME=24 HREF=\"Summary.html\">executive\nsummary</A> of the project, <A\nNAME=29 HREF=\"Administration/Mailing/Overview.html\">Mailing lists</A>\n, <A\nNAME=30 HREF=\"Policy.html\">Policy</A> , November's  <A\nNAME=34 HREF=\"News/9211.html\">W3  news</A> ,\n<A\nNAME=41 HREF=\"FAQ/List.html\">Frequently Asked Questions</A> .\n<DL>\n<DT><A\nNAME=44 HREF=\"../DataSources/Top.html\">What's out there?</A>\n<DD> Pointers to the\nworld's online information,<A\nNAME=45 HREF=\"../DataSources/bySubject/Overview.html\"> subjects</A>\n, <A\nNAME=z54 HREF=\"../DataSources/WWW/Servers.html\">W3 servers</A>, etc.\n<DT><A\nNAME=46 HREF=\"Help.html\">Help</A>\n<DD> on the browser you are using\n<DT><A\nNAME=13 HREF=\"Status.html\">Software Products</A>\n<DD> A list of W3 project\ncomponents and their current state.\n(e.g. <A\nNAME=27 HREF=\"LineMode/Browser.html\">Line Mode</A> ,X11 <A\nNAME=35 HREF=\"Status.html#35\">Viola</A> ,  <A\nNAME=26 HREF=\"NeXT/WorldWideWeb.html\">NeXTStep</A>\n, <A\nNAME=25 HREF=\"Daemon/Overview.html\">Servers</A> , <A\nNAME=51 HREF=\"Tools/Overview.html\">Tools</A> ,<A\nNAME=53 HREF=\"MailRobot/Overview.html\"> Mail robot</A> ,<A\nNAME=52 HREF=\"Status.html#57\">\nLibrary</A> )\n<DT><A\nNAME=47 HREF=\"Technical.html\">Technical</A>\n<DD> Details of protocols, formats,\nprogram internals etc\n<DT><A\nNAME=40 HREF=\"Bibliography.html\">Bibliography</A>\n<DD> Paper documentation\non  W3 and references.\n<DT><A\nNAME=14 HREF=\"People.html\">People</A>\n<DD> A list of some people involved\nin the project.\n<DT><A\nNAME=15 HREF=\"History.html\">History</A>\n<DD> A summary of the history\nof the project.\n<DT><A\nNAME=37 HREF=\"Helping.html\">How can I help</A> ?\n<DD> If you would like\nto support the web..\n<DT><A\nNAME=48 HREF=\"../README.html\">Getting code</A>\n<DD> Getting the code by<A\nNAME=49 HREF=\"LineMode/Defaults/Distribution.html\">\nanonymous FTP</A> , etc.</A>\n</DL>\n</BODY>\n",
>       "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.\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- **Software Products**\n  A list of W3 project components and their current state. (e.g. Line Mode ,X11 Viola , NeXTStep , Servers , Tools , Mail robot , Library )\n- **Technical**\n  Details of protocols, formats, program internals etc\n- **Bibliography**\n  Paper documentation on W3 and references.\n- **People**\n  A list of some people involved in the project.\n- **History**\n  A summary of the history of the project.\n- **How can I help ?**\n  If you would like to support the web..\n- **Getting code**\n  Getting the code by anonymous FTP , etc.",
>       "metadata": {
>         "content_type": "text/html",
>         "fetched_at": "2026-11-19T00:31:24Z",
>         "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
>   }
> }
> ```

## Page Metadata

A result with `status.type` `ok` or `not_modified` has `metadata`, whatever `formats` asks for. To get only metadata, send `"formats": []`.

`metadata` always has `source_url`, the URL the content came from after redirects. It can also have `title`, `description`, `language`, `author`, `published_date`, `content_type`, `origin`, `fetched_at`, and `last_modified`. Other meta tags in the page's `<head>` with a non-empty `name`, `property`, or `itemprop` attribute and a non-empty value appear under their lowercased name, such as `og:title` or `viewport`: a string, or an array of the distinct values 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": "70790b54-ce2f-49b8-830a-c144393db49b",
>   "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-19T11:23:52Z",
>         "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-16",
>         "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"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

## Freshness

By default, the API returns a stored copy of a page if it was fetched in the last two days (`max_age_seconds` `172800`), and fetches the page live otherwise. `metadata.origin` shows which one you got: `cached` for a stored copy, or `live` for a page fetched for this request. `metadata.fetched_at` is when that content was fetched. A stored copy is returned without contacting the site, so that result can't fail because the site is slow or down.

Raise `max_age_seconds` to accept older copies, up to `63072000` (two years). Set it to `0` to always fetch the page live:

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

client = Perplexity()

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();

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}
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
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "0e3f4429-8c3a-4fd4-a32e-ea7889fcb288",
>   "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.\n\nهذا النطاق مُخصص للاستخدام في أمثلة التوثيق دون الحاجة إلى إذن. هذه ليست خدمة، يُرجى تجنب الاعتماد عليها لأغراض الاختبار والمراقبة.\n\n该域名仅用于文档示例，无需获得许可。这并非一项服务，请勿将其用于测试和监控目的。\n\nL’usage de ce domaine est réservé à des exemples de documentation, sans autorisation préalable. Il ne s’agit pas d’un service ; son utilisation à des fins de test ou de surveillance est à éviter.\n\nДанный домен предназначен для использования в примерах документации без необходимости получения предварительного разрешения. Это не сервис; не рекомендуется его использование для тестирования и мониторинга.\n\nEste dominio está destinado al uso en ejemplos de documentación sin necesidad de permiso. Esto no es un servicio; evitar utilizarlo para realizar pruebas o monitoreos.",
>       "metadata": {
>         "content_type": "text/html; charset=utf-8",
>         "fetched_at": "2026-11-19T18:29:44Z",
>         "language": "en",
>         "origin": "live",
>         "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"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

### 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 `max_age_seconds` 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": "136eff5f-e020-4b5f-b6ab-83eb32d6896e",
>   "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-19T11:23:52Z",
>         "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-16",
>         "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"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

### 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`. `metadata.last_modified` is present only when the site sends a `Last-Modified` header, and it is already in the required [`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since) date format, such as `Thu, 03 Dec 1992 08:37:20 GMT`. A conditional request takes exactly one URL and `max_age_seconds` `0`; any other date format, URL count, or `max_age_seconds` returns `400`.

If the page hasn't changed, its result has `status.type` `not_modified` and `metadata`, but no content, so keep the content from your earlier request. If the site returns the page instead of `304`, because it changed or the site doesn't support conditional requests, the result is a normal `ok` result, and a failed fetch has its usual failure status. 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": "6b2f390c-3f60-4e0f-97a0-72027872c61a",
>   "results": [
>     {
>       "metadata": {
>         "fetched_at": "2026-11-19T18:29:46Z",
>         "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"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

## Timeouts

`timeout_ms` is the time budget for fetching the pages, `30000` by default; the response can take slightly longer than this budget. URLs are fetched in parallel. 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`. The [API reference](https://docs.perplexity.ai/api-reference/context-post.md) lists the allowed range, which is lower with [criteria](https://docs.perplexity.ai/docs/context/criteria.md).

## Handle Errors

### Per-URL Status

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`, and is not billed. `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` | The fetch succeeded. The result has `metadata` and the requested formats that are available. |
| `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. |

In this request, 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
```

> [accordion] Response
>
> ```json theme={null}
> {
>   "request_id": "d7fca302-f7f6-48c2-a73e-772359ec7015",
>   "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-19T16:36:31Z",
>         "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"
>     }
>   ],
>   "usage": {
>     "cost": {
>       "currency": "USD",
>       "total_cost": 0.001
>     },
>     "fetched_urls": 1
>   }
> }
> ```

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

### Request 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 the Context API returns itself also have `request_id`. A `401` means the API key is missing or invalid, and a `403` means your organization's API access settings don't allow this request. A `400` means the request needs a fix, because sending it again unchanged fails the same way. You can retry a `429` or a `5xx` error; if the response has a `Retry-After` header, wait that many seconds first. The [API reference](https://docs.perplexity.ai/api-reference/context-post.md) lists the documented status codes and error types.

## Next Steps

> [card] [Score Pages with Criteria](https://docs.perplexity.ai/docs/context/criteria.md)
>
> Score each fetched page with yes or no questions and filter on the scores

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

> [card] [Reading List Q\&A Cookbook](https://docs.perplexity.ai/docs/cookbook/examples/context-api-reading-list-qa/README.md)
>
> Fetch highlights for a question and answer it with numbered citations

> [card] [Context API Pricing](https://docs.perplexity.ai/docs/getting-started/pricing.md#context-api-pricing)
>
> Billing per fetched URL and for criteria scoring
