Overview
Thefetch_url tool fetches and extracts content from specific URLs during an Agent API request. Use it when your application already knows which page, article, document, or report the model should inspect.
Use fetch_url when you need full page content from known URLs. Use web_search when the model first needs to discover relevant pages.
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="openai/gpt-5.6-sol",
input="Explain Bayesian inference: how prior beliefs are updated to posterior beliefs given new evidence, with a concrete medical-test example.",
tools=[
{
"type": "fetch_url"
}
],
instructions="Fetch the URL before summarizing it.",
)
print(response.output_text)
import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const response = await client.responses.create({
model: 'openai/gpt-5.6-sol',
input: 'Explain Bayesian inference: how prior beliefs are updated to posterior beliefs given new evidence, with a concrete medical-test example.',
tools: [
{
type: 'fetch_url' as const,
},
],
instructions: 'Fetch the URL before summarizing it.',
});
console.log(response.output_text);
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.6-sol",
"input": "Explain Bayesian inference: how prior beliefs are updated to posterior beliefs given new evidence, with a concrete medical-test example.",
"tools": [
{
"type": "fetch_url"
}
],
"instructions": "Fetch the URL before summarizing it."
}' | jq
Response
Response
{
"id": "resp_02fda963-4ab7-42cc-b446-d446e0dcd3b2",
"created_at": 1779391738,
"model": "openai/gpt-5.6-sol",
"object": "response",
"output": [
{
"results": [
{
"id": 1,
"snippet": "The disease you have tested positive for is very rare, so let’s say that only 1 in every 100 people with your symptoms actually have the disease.\nThe test you took is 99% sensitive, and 94% specific...",
"title": "Bayes' Theorem and Disease Testing - tom rocks maths",
"url": "https://tomrocksmaths.com/2021/08/31/bayes-theorem-and-disease-testing/",
"date": "2021-08-31",
"last_updated": "2026-05-13",
"source": "web"
},
{
"id": 2,
"snippet": "- Suppose that 5 in 1,000 people (0.5%) has a particular disease\n(*prevalence* of the disease).\n- A diagnostic test for the disease has 99% *sensitivity* (if a person has the disease, the test will...",
"title": "Sensitivity and Specificity",
"url": "https://www.nosco.ch/mathematics/en/sensitivity-specificity.php",
"date": null,
"last_updated": "2026-05-17",
"source": "web"
},
{
"id": 3,
"snippet": "Suppose a blood test used to\ndetect the presence of a particular banned sports drug is **99%\n** **sensitive** and **99% ** **specific**.\nThat is, the test will produce 99% **true positive** results...",
"title": "Bayes Theorem - Drug testing",
"url": "https://www.mun.ca/biology/scarr/4250_Bayes_Theorem.html",
"date": null,
"last_updated": "2026-03-14",
"source": "web"
},
{
"id": 4,
"snippet": "A: mammogram positive, B: developing breast cancer in next 2 years\nSuppose that 7% of the general population of women will have a positive mammogram.\nWhat is the probability of developing breast...",
"title": "[PDF] Predictive values Sensitivity and specificity Bayes' Rule",
"url": "https://ani.stat.fsu.edu/~debdeep/p2_s14.pdf",
"date": "2014-01-14",
"last_updated": "2026-02-16",
"source": "web"
},
{
"id": 5,
"snippet": "positive test given the disease\n{ts:800} times the probability\nof disease divided by-- this same probability--\n...\ndisease times probability",
"title": "Bayes' Theorem (with Example!) - YouTube",
"url": "https://www.youtube.com/watch?v=akClB1J6b28",
"date": "2024-12-02",
"last_updated": "2026-03-22",
"source": "web"
},
{
"id": 6,
"snippet": "So if all you know about a woman is that she does the screening and she gets a positive result, you don't have information about symptoms or anything like that,\n{ts:113} you know that she's either...",
"title": "The medical test paradox, and redesigning Bayes' rule - YouTube",
"url": "https://www.youtube.com/watch?v=lG4VkPoG3ko",
"date": "2020-12-22",
"last_updated": "2026-03-31",
"source": "web"
},
{
"id": 7,
"snippet": "The Fagan Nomogram was designed to give a post-test probability based on the pre-test probability and the likelihood ratio of the test being conducted.\n...\nUnfortunately the police test is 80% (0.8)...",
"title": "Bayesian Statistics - The Bottom Line",
"url": "https://www.thebottomline.org.uk/blog/ebm/bayesian-statistics/",
"date": "2020-09-11",
"last_updated": "2026-05-21",
"source": "web"
},
{
"id": 8,
"snippet": "We can apply Bayes' theorem if we know the approximate likelihood that a subject has the disease before they come for screening, this is given by the prevalence of the disease.\n...\nFor an overall...",
"title": "Screening Test Errors (Bayes' Theorem) - StatsDirect",
"url": "https://www.statsdirect.com/help/clinical_epidemiology/screening_test.htm",
"date": null,
"last_updated": "2026-03-07",
"source": "web"
}
],
"type": "search_results",
"queries": [
"Bayes theorem medical test example",
"Bayes rule disease test sensitivity specificity",
"Bayesian inference prior posterior example disease test"
]
},
{
"id": "msg_738a8825-ab21-4f10-bee9-2bdedfa99347",
"content": [
{
"text": "Bayesian inference is a way to update **beliefs** (probabilities) when new data arrive: the prior belief is combined with how likely the data are under different hypotheses to produce a posterior belief. [web:2]\n\n## Core idea and formula\n\nBayes’ theorem in probability form is: [web:2]\n\n\\[\nP(H \\mid E) = \\frac{P(E \\mid H)\\,P(H)}{P(E \\mid H)\\,P(H) + P(E \\mid \\neg H)\\,P(\\neg H)}\n\\] [web:2]\n\n- \\(H\\): hypothesis (e.g., “patient has the disease”). [web:2] \n- \\(E\\): evidence (e.g., “test result is positive”). [web:2] \n- \\(P(H)\\): prior, belief in \\(H\\) before seeing the test. [web:2] \n- \\(P(H \\mid E)\\): posterior, updated belief in \\(H\\) after seeing the test. [web:2] \n- \\(P(E \\mid H)\\), \\(P(E \\mid \\neg H)\\): how likely the evidence is if \\(H\\) is true or false (this is where test accuracy enters). [web:2]\n\nIn words: posterior = (likelihood × prior) / average likelihood of the evidence across all possibilities. [web:2]\n\n## Connecting to medical test terms\n\nFor diagnostic tests, Bayes’ theorem often uses: [web:2]\n\n- Disease \\(D\\) vs no disease \\(\\overline{D}\\). [web:2] \n- Positive test “+” vs negative “–”. [web:2] \n\nKey quantities:\n\n- **Prevalence**: \\(P(D)\\): prior probability that someone from this population has the disease, before considering the test result. [web:2] \n- **Sensitivity**: \\(P(+ \\mid D)\\): probability the test is positive if the person has the disease (true-positive rate). [web:2] \n- **Specificity**: \\(P(- \\mid \\overline{D})\\): probability the test is negative if the person does not have the disease (true-negative rate). [web:2] \n\nThe two main post-test probabilities are: [web:2] \n\n- \\(P(D \\mid +)\\): probability of disease given a positive result (positive predictive value, PPV). \n- \\(P(\\overline{D} \\mid -)\\): probability of no disease given a negative result (negative predictive value, NPV). \n\nBayes’ theorem gives, for a positive test: [web:2]\n\n\\[\nP(D \\mid +) = \\frac{P(+ \\mid D)\\,P(D)}{P(+ \\mid D)\\,P(D) + P(+ \\mid \\overline{D})\\,P(\\overline{D))}\n\\] [web:2]\n\nand \\(P(+ \\mid \\overline{D}) = 1 - \\text{specificity}\\). [web:2]\n\n## Concrete medical-test example\n\nConsider this concrete scenario: [web:2]\n\n- Disease prevalence in the population: \\(P(D) = 0.5\\%\\) (5 in 1,000 people). \n- Sensitivity of the test: 99% → \\(P(+ \\mid D) = 0.99\\). \n- Specificity of the test: 98% → \\(P(- \\mid \\overline{D}) = 0.98\\), so \\(P(+ \\mid \\overline{D}) = 0.02\\). \n\nQuestion: If a randomly chosen person from this population tests positive, what is the probability they actually have the disease, \\(P(D \\mid +)\\)? [web:2]\n\nPlug into Bayes’ formula: [web:2]\n\n\\[\nP(D \\mid +) = \n\\frac{0.99 \\times 0.005}{0.99 \\times 0.005 + 0.02 \\times 0.995}\n\\approx 0.20\n\\] [web:2]\n\nSo even though the test is quite accurate, a positive result means only about a 20% chance (1 in 5) that the person truly has the disease, because the disease is rare. [web:2]\n\n## Interpreting as prior → posterior update\n\nIn that example, Bayesian inference can be read step by step. [web:2]\n\n- Prior belief: Before testing, chance of disease is 0.5% (prevalence). [web:2] \n- Evidence quality: A positive test is much more likely if the person has disease (0.99) than if they do not (0.02), so it is informative but not perfect. [web:2] \n- Posterior belief: After a positive result, the belief jumps from 0.5% to about 20%; this is the updated probability \\(P(D \\mid +)\\). [web:2] \n\nConceptually, the test “boosts” the prior odds of disease by a factor equal to the likelihood ratio \\(\\text{LR}^+ = \\frac{P(+ \\mid D)}{P(+ \\mid \\overline{D})} = \\frac{0.99}{0.02} \\approx 49.5\\), then converts those updated odds back into a probability. [web:2][web:7] \n\nSo Bayesian inference is precisely this: start with a prior probability, adjust it using how strongly the evidence favors one hypothesis over alternatives, and end with a posterior probability that reflects both the original belief and the new data. [web:2][web:7]",
"type": "output_text",
"annotations": [],
"logprobs": []
}
],
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"status": "completed",
"error": null,
"usage": {
"input_tokens": 6282,
"output_tokens": 1258,
"total_tokens": 7540,
"cost": {
"currency": "USD",
"input_cost": 0.01079,
"output_cost": 0.02516,
"total_cost": 0.03988,
"cache_creation_cost": null,
"cache_read_cost": 0.00143,
"tool_calls_cost": 0.0025
},
"input_tokens_details": {
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 3584,
"cached_tokens": 3584
},
"tool_calls_details": {
"search_web": {
"invocation": 1
}
},
"output_tokens_details": {
"reasoning_tokens": 0
}
},
"completed_at": 1779391738
}
When to Use
Use fetch_url when… | Use web_search when… |
|---|---|
| You already have a URL | You need to discover relevant pages |
| You need fuller page content | You need snippets from multiple sources |
| You are summarizing a specific article or document | You are researching a broad topic |
| You want the model to inspect a known source | You want the model to find current sources |
Combine
web_search and fetch_url for multi-step research: search to find relevant pages, then fetch the most important URLs for fuller context.Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Must be "fetch_url". |
max_urls | integer | No | Maximum number of URLs to fetch per tool call. The API schema allows values from 1 to 10. |
Response Shape
Whenfetch_url runs, the response can include a fetch_url_results output item before the final assistant message. Each fetched content item includes the URL, page title, and extracted snippet.
{
"output": [
{
"type": "fetch_url_results",
"contents": [
{
"url": "https://example.com/report",
"title": "Example Report",
"snippet": "Extracted content from the fetched page."
}
]
},
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The answer generated from the fetched URL content."
}
]
}
],
"usage": {
"input_tokens": 900,
"output_tokens": 250,
"total_tokens": 1150,
"tool_calls_details": {
"fetch_url": {
"invocation": 1
}
}
}
}
Error Handling
fetch_url is best-effort. When a URL cannot be fully fetched or extracted, the API can still return a completed Agent API response with the final assistant message explaining what content was available. Check each item in fetch_url_results.contents: successful items contain extracted page text, while failed items contain an explicit marker in snippet for the requested URL.
Failure markers explain the known reason, such as an HTTP client error, a robots-policy block, or rate limiting. If the upstream fetch returns no item for a requested URL, the API adds an item whose snippet includes no_result_returned. Treat these markers as unavailable content rather than page text.
| Case | Response behavior |
|---|---|
| Paywalls and login walls | fetch_url does not bypass access controls. The corresponding content item contains a failure marker explaining that the origin rejected the request and may require credentials or a non-GET method. |
| Redirects | HTTP redirects are followed when the destination can be fetched. In the returned fetch_url_results item, the url field reflects the URL you requested, not the final redirect destination. |
| Non-HTML content | fetch_url extracts whatever text content the server returns at the URL. PDFs, binary downloads, and URLs that serve anti-bot challenge pages may return limited or unrelated extracted content. |
| Timeouts and unreachable URLs | The corresponding content item contains a failure marker with the available reason. If no upstream result is returned, the marker includes no_result_returned. |
Limits / Quotas
Usemax_urls to keep fetches bounded and predictable. Fewer URLs usually produce lower latency and leave more context for the model’s reasoning and final answer.
| Limit | Value |
|---|---|
| Maximum URLs per tool call | max_urls can be set from 1 to 10. |
| Supported URL schemes | Use absolute http:// or https:// URLs. Other schemes (file:, data:, ftp:, browser-extension URLs) are not supported and produce no usable content. |
| Content size | Fetched content is extracted into snippets for model context and may be truncated for longer pages. |
Pricing
fetch_url is billed at $0.50 per 1,000 invocations. Model token usage is billed separately according to Agent API token pricing.
Pricing follows the same pattern as other tool calls: pay for tool invocations plus model tokens. See Pricing.
Next Steps
Web Search
Search the web before fetching source content.
Finance Search
Retrieve structured financial and market data.
People Search
Search for professionals and employees.
API Reference
View complete endpoint documentation.