Perplexity Decisions API can read a page from a URL, with max_staleness for freshness (November 2026)

What you get

In November 2026 Perplexity let the Decisions API (POST /v1/decisions) read a web page from a URL. It builds on web grounding. Set mode to "web_grounding" and pass a page URL as state. The API fetches the page, swaps the URL in state for the page text, then runs its usual searches. The model answers from the page text plus the search evidence.

• New response field: fetched_results sits next to search_results. It holds at most one item, with title, url and snippet. The snippet is the page text, up to 40,000 characters. The url is normalized, so it may not match what you sent exactly.
• Freshness with max_staleness: the maximum age of the page in seconds since its last crawl, as a non-negative integer. 86400 allows a copy crawled in the past 24 hours. An older copy triggers a fresh crawl. Leave it out to use a stored copy of any age. It does not filter search results.
• Price: each successful fetch costs $0.001, on top of searches and input tokens. A failed fetch is free. The page text is billed as input tokens and counts toward the 256K input limit.
• Speed: the fetch runs before search and adds up to about 250 ms.

Prerequisites

• A Perplexity API key in PERPLEXITY_API_KEY
• Any HTTP client, or the Python or TypeScript SDK

Steps

1. Put the URL alone in state. It must be a single http://, https:// or www. URL. A text part holding only the URL works too. A URL mixed with other words, such as "Read https://example.com/page", is searched as text, not fetched.
2. Add "mode": "web_grounding" and, if you want fresh pages, :