Scrape JSON

Extract structured, strongly-typed JSON from a single page with the Scrape JSON endpoint, using a natural language prompt instead of CSS selectors or XPath.

Scrape a single page and return structured JSON. The general agent analyzes the page against your prompt and returns clean, strongly-typed data without fragile CSS selectors or custom XPath parsers.

Note

  • Use the Scraper API Server (https://api.mrscraper.com) host when calling this endpoint.
  • The prompt only parses the scraped content. It cannot instruct the scraper itself.
  • To shape the output with a JSON schema, append it to the prompt as a Json Schema: section.
  • Send every field in the query string, URL-encoded. A request URL over about 8 KB is refused with 414, so send a long prompt (for example one with a JSON schema) as a POST with url, prompt and agent in a JSON body.
  • The tokens used are in the token_usage response header and field. A failed run returns success: false and is not billed.
  • See Scrape JSON in the Scraper API guide for the full list of settings.
GET
/

Query Parameters

token*string

API token.

url*string

URL-encoded URL of the page you want to scrape, such as https%3A%2F%2Fquotes.toscrape.com%2F. Must include the protocol (https://).

Formaturi
prompt?string

URL-encoded description of the data shape you want back, for example fields like title, price, and rating. The prompt only parses the scraped content — it cannot instruct the scraper itself. To shape the output with a JSON schema, append it to the prompt as a 'Json Schema:' section. A request URL over about 8 KB is refused with 414, so send a longer prompt as a POST with a JSON body.

Default"Extract all data as complete as possible."
agent*string

The AI agent used for extraction. Scrape JSON uses the general agent, optimised for single-page structured extraction.

Default"general"
Value in"general"
html?boolean

Returns the raw HTML of the scraped page in the response.

Defaulttrue
browserRendering?boolean

Controls whether the page is loaded in a browser. Leave it out to load the page without a browser first and switch to a browser automatically if the request is blocked. Set true to always load the page in a browser, which JavaScript-heavy sites, SPAs, and pages that load content dynamically need. Set false to never use a browser.

waitUntil?string

Defines when the browser considers navigation complete. networkidle0 waits until all network activity stops — the most thorough option, but the slowest.

Default"domcontentloaded"
Value in"domcontentloaded" | "load" | "networkidle0" | "networkidle2"
timeout?integer

Maximum seconds to wait for the page to fully load before the request times out. Increase for slow or complex pages.

Default300
screenshot?boolean

Captures a screenshot of the rendered page as a base64-encoded image. Useful for verifying what the scraper actually saw.

Defaultfalse
super?boolean

Routes the request through a real device to improve results on complex websites. On by default; set to false to use standard routing.

Defaulttrue
geoCode?string

Country to load the page from. Defaults to the United States.

Default"us"
proxyCountry?string

Country of the proxy server. Defaults to the United States.

Default"us"
saveResult?boolean

Saves the result to the Result tab.

Defaulttrue
maxAge?integer

Serves a cached result of the same request when it is newer than this age, in milliseconds, such as 86400000 for 1 day. Up to 604800000 (7 days). Omit or send 0 to always scrape fresh. A cached result costs the same tokens as the original scrape.

Range0 <= value <= 604800000
tokenCap?integer

Maximum total tokens the scrape and its retries can use. Automatic retries are bounded by this cap, so the total tokens for a single run stay at or below the value you set. Omit for no limit.

Range1 <= value
maxRetries?integer

Maximum number of retries for the request. Omit for no limit.

Range0 <= value

Header Parameters

x-api-token*string

API token.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://api.mrscraper.com/?token=string&url=https%3A%2F%2Fquotes.toscrape.com%2F&prompt=Extract+all+data+as+complete+as+possible.&agent=general" \  -H "x-api-token: string"
{
  "success": true,
  "data": {
    "site": {
      "name": "Quotes to Scrape",
      "url": "https://quotes.toscrape.com/",
      "navigation": [
        {
          "label": "Login",
          "url": "/login"
        }
      ]
    },
    "quotes": [
      {
        "text": "The world as we have created it is a process of our thinking. It cannot be changed without changing our thinking.",
        "author": "Albert Einstein",
        "author_url": "/author/Albert-Einstein",
        "tags": [
          {
            "name": "change",
            "url": "/tag/change/page/1/"
          },
          {
            "name": "deep-thoughts",
            "url": "/tag/deep-thoughts/page/1/"
          }
        ]
      },
      {
        "text": "It is our choices, Harry, that show what we truly are, far more than our abilities.",
        "author": "J.K. Rowling",
        "author_url": "/author/J-K-Rowling",
        "tags": [
          {
            "name": "abilities",
            "url": "/tag/abilities/page/1/"
          },
          {
            "name": "choices",
            "url": "/tag/choices/page/1/"
          }
        ]
      }
    ],
    "pagination": {
      "next": {
        "label": "Next →",
        "url": "/page/2/"
      }
    }
  },
  "thread_id": "01a1e8cb-0fb2-7d42-a67c-38c57e9e77eb",
  "token_usage": 10,
  "html": "",
  "markdown": "",
  "screenshot": "",
  "status": "Results ready",
  "error": "",
  "runtime": 16.636244,
  "cookies": []
}
{
  "message": "Unauthorized access",
  "data": null
}
{
  "error": "All upstream servers are unavailable"
}
{
  "error": "Scrape timed out: the scraper did not answer in time"
}