跳到正文
基础工具1 credit

fetch_url

抓取并解析网页,支持自动处理重定向、超时控制和自定义请求头。非常适合从任何可公开访问的 URL 获取 HTML 内容。

使用场景

获取页面内容

从任意网页抓取 HTML 内容,用于后续处理或分析

获取 API 数据

向 REST API 发起 GET 请求并获取 JSON 响应

健康检查

监控网站可用性和响应时间

简单下载

下载静态资源、文档或页面内容

Endpoint

POST/api/v1/tools/fetch_url
Auth Required
Free 计划 1 req/s
1 credit

Parameters

NameTypeRequiredDefaultDescription
url
stringRequired-
要抓取的 URL(必须包含协议:http:// 或 https://)
Example: https://example.com
headers
objectOptional-
请求中要包含的自定义 HTTP 请求头
Example: {"Accept": "text/html", "User-Agent": "MyBot/1.0"}
timeout
numberOptional10000
请求超时时间,单位毫秒(1000-30000)
Example: 15000
follow_redirects
booleanOptionaltrue
是否自动跟随 HTTP 重定向
Example: true
user_agent
stringOptional-
自定义 User-Agent 请求头(覆盖默认值)
Example: Mozilla/5.0 (compatible; CrawlBot/1.0)
respect_robots
booleanOptionaltrue
遵守目标站点的 robots.txt。保持 `true` 时,robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝,且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`,并且该覆盖会记录到你的 API key 上。
Example: true
max_inline_chars
numberOptional40000
内联返回的最大结果大小,以其 JSON 的字符数计(1,000-10,000,000)。超过后,响应会携带 `preview`(正文的前 `max_inline_chars` 个字符)、`result_handle`、`total_chars`、`truncated: true` 和 `expires_at`,其余部分由 [read_result](/docs/api-reference/tools/read-result) 读取,每次调用 1 credit。已存储的结果保留 1 小时。
Example: 40000

请求示例

cURL

terminalBash
curl -X POST https://crawlforge.dev/api/v1/tools/fetch_url \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "timeout": 15000,
    "follow_redirects": true
  }'

TypeScript

fetchUrl.tsTypescript
// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

const result = await client.fetchUrl({
  url: 'https://example.com',
  timeout: 15000,
  headers: {
    'Accept': 'text/html',
    'Accept-Language': 'en-US',
  },
});

// result.data is untyped in crawlforge-sdk 0.1 — its shape is the Response Example below.
const page = result.data as { url: string; status: number; content_length: number };
console.log('Page fetched:', page.url);
console.log('Status:', page.status);
console.log('Content length:', page.content_length);
console.log('Credits used:', result.creditsUsed);
console.log('Credits remaining:', result.creditsRemaining);

Python

fetch_url.pyPython
# pip install crawlforge
from crawlforge import CrawlForge

client = CrawlForge()  # reads CRAWLFORGE_API_KEY

result = client.fetch_url(
    url='https://example.com',
    timeout=15000,
    headers={
        'Accept': 'text/html',
        'Accept-Language': 'en-US',
    },
)

# result.data is a plain dict — its shape is the Response Example below.
page = result.data
print(f"Page fetched: {page['url']}")
print(f"Status: {page['status']}")
print(f"Content length: {page['content_length']}")
print(f"Credits used: {result.credits_used}")
print(f"Credits remaining: {result.credits_remaining}")

响应示例

200 OK245ms
{
"success": true,
"data": {
"url": "https://example.com",
"status": 200,
"status_text": "OK",
"headers": {
"content-type": "text/html; charset=UTF-8",
"content-length": "1256",
"server": "nginx"
},
"content": "Example Domain......",
"content_length": 1256,
"content_type": "text/html; charset=UTF-8",
"redirected": false,
"final_url": "https://example.com",
"response_time_ms": 245
},
"credits_used": 1,
"credits_remaining": 999,
"processing_time": 245
}
Field Descriptions
data.url请求的原始 URL
data.status响应的 HTTP 状态码
data.content页面的完整 HTML 内容
data.content_length内容大小,单位字节
data.final_url跟随重定向后的最终 URL
data.response_time_ms目标响应并传输正文所用的时间(毫秒)
credits_used本次请求扣除的 credits(每次抓取 1 个)
credits_remaining你剩余的 credit 余额

错误处理

无效 URL(400 Bad Request)

URL 格式无效。请确保它包含协议(http:// 或 https://)

超时错误(500 Internal Server Error)

请求耗时超过了指定的超时时间。请尝试增大 timeout 参数。

credits 不足(402 Payment Required)

你的账户 credits 不足。购买更多 credits 或 升级你的计划。

超出速率限制(429 Too Many Requests)

你已超出计划的速率限制。请稍候片刻,或 升级你的计划 以获得更高的限额。

被 robots.txt 拦截(403 Forbidden)

目标站点的 robots.txt 对 CrawlForge 禁止了该路径。若你与目标站点另有约定,可设置 respect_robots: false 予以覆盖——该覆盖会记录到你的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值,这类主机一律被拒绝。

credit 费用

1 credit
每次请求 1 credit
每次成功的 fetch_url 请求花费 1 credit,与页面大小或响应时间无关。

Free 计划: 1,000 个一次性试用 credits = 1,000 次请求

Hobby 计划: 每月 5,000 credits = 5,000 次请求($19/mo)

Professional 计划: 每月 100,000 credits = 100,000 次请求($99/mo)

Business 计划: 每月 500,000 credits = 500,000 次请求($399/mo)

相关工具