POST /v1/scrape

Scrape a single URL and return its content as clean markdown. Optionally extract structured listing data (business name, phone, address, hours, rating, and more) using a JSON-LD cascade + heuristic pipeline, no LLM cost.

The engine automatically escalates the fetch method when needed: plain HTTP first, then headless Playwright, then stealth mode for bot-protected pages.

Request

POST /v1/scrape
Content-Type: application/json
x-api-key: YOUR_KEY

Body

Field	Type	Required	Default	Description
`url`	string	Yes		The URL to scrape. Must be a valid `http://` or `https://` URL.
`formats`	string[]	No	`["markdown"]`	Which outputs to return: `markdown`, `rawHtml`, `links`, `screenshot`, `json`, `branding`, `summary`. Requested outputs appear under a `formats` object.
`includeHtml`	boolean	No	`false`	Shortcut for including raw HTML in the response.
`extractListing`	boolean	No	`true`	Run the listing extraction pipeline (JSON-LD → Open Graph → regex).
`schema` / `jsonSchema`	object	No		When `formats` includes `json`, extract structured data matching this schema via the LLM layer.
`actions`	object[]	No		Browser actions before capture (forces Playwright): `click`, `scroll`, `wait`, `write`, `press`, `screenshot`, `executeJavascript`, `pdf`.
`onlyMainContent`	boolean	No	`false`	Strip nav/boilerplate, keep the main content.
`includeTags` / `excludeTags`	string[]	No		Keep only / drop these CSS selectors before conversion.
`removeBase64Images`	boolean	No	`false`	Strip inline base64 images from the markdown.
`forcePlaywright`	boolean	No	`false`	Skip plain fetch and render with Playwright.
`waitFor`	number	No		Milliseconds to wait after load before capture (Playwright).
`cookies` / `headers`	string / object	No		Cookie string and custom headers forwarded with the request.
`ignoreRobotsTxt`	boolean	No	`false`	Respect robots.txt by default; set `true` to opt out (Firecrawl-compatible).
`maxAge`	number	No	`0`	Serve a cached copy if fresher than this many ms. `0` = always fresh.
`location`	object	No		`{ country }` proxy/geo hint for the fetch.

Example request

curl -X POST https://api.superscraper.dev/v1/scrape \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.yelp.com/biz/acme-plumbing-austin",
    "extractListing": true
  }'

Response

HTTP 200 on success, HTTP 422 if the page could not be fetched.

Body

Field	Type	Description
`url`	string	Canonical URL after any redirects
`markdown`	string	Page content converted to clean markdown
`html`	string \| undefined	Raw HTML (only present when `includeHtml: true`)
`listing`	object \| null	Structured listing data (see below)
`formats`	object	Requested outputs, e.g. `formats.markdown`, `formats.links`, `formats.json` (present when `formats[]` was set)
`metadata.fetchMethod`	string	How the page was fetched: `"fetch"`, `"playwright"`, `"spider"`, or `"browserbase"`
`metadata.extractionMethod`	string	Listing extraction layer used
`metadata.confidence`	number	Listing confidence, 0–1
`metadata.cached`	boolean	Whether this response was served from cache
`metadata.cacheAgeMs`	number	Age of the cached copy (present when `cached: true`)
`metadata.latencyMs`	number	Total fetch + extraction time in milliseconds

A .pdf URL (or application/pdf content type) short-circuits to PDF extraction and returns { url, text, markdown, isPdf, ok }. A blocked private/loopback/metadata target returns 400 Blocked URL. | ok | boolean | true on success | | error | string | undefined | Error message when ok is false |

Listing object

Populated when extractListing: true and the page contains business/listing signals.

Field	Type	Description
`name`	string	Business name
`description`	string	Short description
`phone`	string	Primary phone number
`email`	string	Contact email
`website`	string	Business website URL
`address`	string	Street address
`city`	string	City
`state`	string	State / province
`zip`	string	Postal code
`country`	string	Country
`lat`	number	Latitude
`lng`	number	Longitude
`rating`	number	Average rating (e.g. `4.7`)
`review_count`	number	Total review count
`price_range`	string	Price range string (e.g. `"$$"`)
`price_min`	number	Minimum price
`price_max`	number	Maximum price
`hours`	object	Business hours (structure varies by source)
`amenities`	string[]	List of amenities or features
`hero_image`	string	URL of the primary image
`photo_urls`	string[]	All photo URLs
`license_number`	string	Professional license number
`capacity`	number	Capacity (e.g. for venues)
`founded_year`	number	Year the business was founded
`schema_markup_types`	string[]	JSON-LD `@type` values found on the page
`_confidence`	number	Extraction confidence score (0–1)
`_extraction_method`	string	Which method populated the data: `"json-ld"`, `"microdata"`, or `"heuristic"`

Example response

{
  "url": "https://www.yelp.com/biz/acme-plumbing-austin",
  "markdown": "# Acme Plumbing\n\n**4.8** ★ · 214 reviews · Plumbing · Austin, TX\n\n> Licensed & insured. Same-day service available.\n\n## Contact\n\n- **Phone:** (512) 555-0187\n- **Address:** 1402 S 1st St, Austin, TX 78704\n\n## Hours\n\nMon–Fri 7am–7pm · Sat 8am–5pm · Sun Closed",
  "listing": {
    "name": "Acme Plumbing",
    "phone": "(512) 555-0187",
    "address": "1402 S 1st St",
    "city": "Austin",
    "state": "TX",
    "zip": "78704",
    "country": "US",
    "lat": 30.2468,
    "lng": -97.7572,
    "rating": 4.8,
    "review_count": 214,
    "price_range": "$$",
    "hours": {
      "monday": "7:00 AM – 7:00 PM",
      "tuesday": "7:00 AM – 7:00 PM",
      "wednesday": "7:00 AM – 7:00 PM",
      "thursday": "7:00 AM – 7:00 PM",
      "friday": "7:00 AM – 7:00 PM",
      "saturday": "8:00 AM – 5:00 PM",
      "sunday": "Closed"
    },
    "hero_image": "https://s3-media1.fl.yelpcdn.com/bphoto/acme-hero.jpg",
    "_confidence": 0.92,
    "_extraction_method": "json-ld"
  },
  "metadata": {
    "fetchMethod": "plain",
    "latencyMs": 487
  },
  "ok": true
}

Rate limits by tier

Plan	Requests / minute	Credits / month
Free	10	1,000
Hobby	60	5,000
Pro	200	100,000
Scale	600	500,000
Custom	3 000	Custom

Authentication Extract