Response Selector

The response selector lets you filter the scraped content to return only the elements you care about, instead of the entire page. This dramatically reduces response size and simplifies downstream parsing.

Set the responseSelector parameter to any valid CSS selector or XPath query. Matching elements are extracted and wrapped in a <scrapi> root element for valid, parseable HTML.

When To Use This

Targeted data extraction - Pull only product prices, article text, table data, or any specific section without parsing the full page.
Reducing response payload - Smaller responses mean faster processing, lower bandwidth, and less storage for archival or pipeline ingestion.
Simplified parsing - Extract a single element or group of elements and skip complex HTML traversal logic in your application.
Combining with Markdown - Use a selector to isolate content, then combine with Markdown response format for perfectly clean text output.

How It Works

ScrAPI scrapes the full page as normal.
The responseSelector is applied to the complete HTML.
All matching elements are extracted and wrapped in a <scrapi> root tag.
Only the filtered content is returned in the response.

If using Markdown format, the selected HTML is converted to Markdown - no extra wrapping is added.

Example Request

POST https://api.scrapi.tech/v1/scrape

CSS Selector

{
  "url": "https://deventerprise.com",
  "responseSelector": ".title h2"
}

XPath Query

{
  "url": "https://deventerprise.com",
  "responseSelector": "//div[@class='title']/h2"
}

Example Response (HTML)

<scrapi>
<h2>
  DevEnterprise Software Limited
  <p>
    DevEnterprise provides custom software solutions for companies and individuals using enterprise level development techniques and services.
  </p>
</h2>
</scrapi>

The <scrapi> root tag ensures the response is always valid HTML/XML, making it compatible with standard parsers.

Example Response (Markdown)

When combined with Markdown response format, there is no wrapping - just clean text:

## DevEnterprise Software Limited
DevEnterprise provides custom software solutions for companies and individuals using enterprise level development techniques and services.

Error Handling

If you supply an invalid CSS selector or XPath query, the full page content is returned instead. The error details appear in the errorMessages field (JSON format) or X-ScrAPI-ErrorMessages header (HTML/Markdown format).

HTML or Markdown Response - Combine selectors with Markdown for the cleanest text extraction.
Real Browser - Use a browser to ensure dynamic content is rendered before applying selectors.
Browser Commands - Interact with the page first (e.g., expand sections) before applying a selector to the final state.

Testing

Test this request in the Playground or view the OpenAPI specification.

HTML or Markdown Response Take Screenshot