Scrape Parameters
The complete request and response contract for POST /api/v1/scrape.
/api/v1/scrape/bulk endpoint; run multiple authenticated requests from your worker when you need a batch.Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Required | HTTP or HTTPS URL to scrape. Example: |
extract_options | array[string] | Optional | Fields to request: title, text, links, images, metadata, or all. Default: ["title", "text"] Example: |
follow_internal_links | boolean | Optional | Follow internal links discovered on the primary page. Requires Unicorn. Default: false Example: |
max_pages | integer | Optional | Maximum discovered internal pages when following links. Allowed range: 1–50. Default: 10 Example: |
include_contacts | boolean | Optional | Extract contacts from page text. Requires Starter or higher. Default: false Example: |
Credit Calculation
follow_internal_links: true and max_pages: 3, the maximum reservation is 11 credits (5 + 3 × 2). Failed pages are refunded after settlement.Response Fields
| Field | Type | Description |
|---|---|---|
url | string | Normalized primary URL. |
primary_content | object | Structured content for the primary page. |
discovered_links | array | Scraped internal pages when link following is enabled. |
links_scraped | integer | Completed discovered pages without an error. |
contacts | array | Included only when include_contacts is true. |
credits_used | integer | Final charge after completed work is settled. |
remaining_credits | integer | Account balance after the request. |
success | boolean | True when primary_content.error is empty. |
Valid Request
curl -X POST https://search.venym.io/api/v1/scrape \
-H "Authorization: Bearer $VENYM_SEARCH_API_KEY" \
-H "Content-Type: application/json" \
--data '{"url":"https://example.com","extract_options":["title","text","metadata"]}'A valid API key can call Scrape. include_contacts requires Starter or higher; follow_internal_links requires Unicorn. These failures return 403.