Featured-snippet candidates
Extract paragraphs, lists, and tables that look like featured-snippet candidates — from HTML you provide OR from a URL we fetch.
/v1/seo/snippet-candidates Pulls three kinds of snippet candidates: paragraphs in the 30–80 word band after each <h2> (tagged quality: "ideal" for the classic 40–55 window, "acceptable" otherwise), unordered and ordered lists with 3+ items, and tables with 2+ rows × 2+ columns. Each candidate includes the heading it sits under so a downstream editor can review them in context. Caller writes their own logic to pick the strongest per query.
Two input modes:
• html: caller supplies the HTML directly (no fetch, free).
• url: we fetch the URL on the caller's behalf. With use_residential_proxy: true the fetch routes via our residential pool with JS rendering — finds snippets on JS-hydrated docs sites that have 0 <p> tags in their server-rendered HTML. Bills +3 credits.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| html | string | no | — | HTML to extract from. Body limit 1 MB. Provide this OR url. |
| url | string | no | — | Alternative to html. We fetch the page for you. |
| use_residential_proxy | boolean | no | false | Only meaningful with url. Premium fetch via residential pool with JS rendering. Bills +3 credits. |
| max_per_kind | integer | no | 5 | Cap per kind (paragraphs / lists / tables). Range 1–50. |
Request
curl -X POST https://api.qcrawl.com/v1/seo/snippet-candidates \
-H "Authorization: Bearer osk_..." \
-d '{"html": "<article><h2>How big is the free tier?</h2><p>The free tier covers 1,000 requests per month across every endpoint. No credit card is required at signup, and credits do not roll over between billing periods. Upgrade only when you need more.</p></article>"}'Response
{
"status": "success",
"paragraphs": [
{"heading": "How big is the free tier?", "snippet": "The free tier covers 1,000 requests per month...", "word_count": 40}
],
"lists": [],
"tables": [],
"total_candidates": 1
}