Run a dedicated scraper
run_scraperRun a dedicated scrape endpoint with its own parameters.
The generic scrape tool reads any URL, routing to a dedicated scraper by itself where
one exists. Use this when at least one of these holds: you need parameters scrape
lacks (pagination, sort order, store or delivery location and the like), or you need
the content a dedicated parser returns structured, described below. Dedicated scrapers
exist only for major sites (big search engines, marketplaces, retailers, video platforms
and AI chats); most sites have none. Look the endpoint up with list_scrapers(), read
its parameters with list_scrapers(endpoint), then call it here.
An endpoint with a dedicated parser returns its parsed JSON by default; set output in
params (e.g. ["markdown"]) to read the page instead. Other endpoints return Markdown
wherever they offer it, unless output says otherwise; for structured data from them,
describe the fields in json_prompt.
Endpoints with a dedicated parser return typical page content in a predefined shape:
search results (organic links, ads, images, news, videos, SERP extras), product
listings and details (title, price, stock, seller, reviews), seller profiles,
bestsellers, hotel offers, AI chat answers (prompt, response, citations), YouTube
video and channel metadata. That runs first; with no dedicated parser, or one that
failed or returned nothing, the AI parser extracts what json_prompt describes. The
result's parser says which one answered, and parser_note carries the dedicated
parser's own verdict (e.g. PARSE_PARTIAL_SUCCESS_SOME_FIELDS_DEFAULT). If a dedicated result
lacks what you need, call again with parser="ai".
To run several URLs or queries with the same parameters, give url or query in
params as a list: a few run side by side, more go to the endpoint's batch in one
request, and the call waits for them. The reply has an item per URL or query, as
scrape gives for a list. A batch cannot fall back from the dedicated parser to the AI
parser item by item: run the ones it failed again with parser="ai".
Calls run synchronously. One that times out is sent to the corresponding asynchronous
endpoint (/v1/async/...) and returns a request_id to collect with check_requests;
an async/... endpoint, or one list_scrapers lists only in async form, is always
queued.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"endpoint": "<endpoint>",
"params": "<params>"
},
"name": "run_scraper"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes | The endpoint's own request body. Get its JSON Schema from `list_scrapers(endpoint)` rather than guessing the keys. Give `url` or `query` as a list to run several that share every other parameter. | |
| parser | No | auto uses the endpoint's dedicated parser when it has one and falls back to the AI parser when that fails or returns nothing. ai goes straight to the AI parser — use it when a dedicated result lacked the fields you need. | auto |
| endpoint | Yes | A scrape endpoint path from `list_scrapers`, without the /v1/ prefix, e.g. 'scrape/amazon/search'. | |
| structured | No | Return parsed JSON instead of page content. Implied by `json_prompt` or `json_schema`, and by an endpoint with a dedicated parser unless `output` in `params` asks for content. The dedicated parser runs first when there is one. | |
| json_prompt | No | Fields to pull out as JSON, in plain words: name them and say what shape you want. Used by the AI parser, which runs when the endpoint has no dedicated parser or its dedicated parser did not return them. Pass this or `json_schema`, not both. Leave unset to read the content yourself. | |
| json_schema | No | A JSON Schema the AI parser's output must follow, instead of `json_prompt`: the two cannot be combined. Use it when you need the exact same shape off many pages. |