SCRAPE APILive

Scrape API

Fetch a webpage through the Venym execution backend and receive clean, structured content. Use optional internal-link following for controlled crawls.

Base charge

5 credits

Every Scrape request

Link following

+2 / page

Only for completed pages

Output

Structured JSON

Text, links, metadata, errors

01 · Endpoint

POSThttps://search.venym.io/api/v1/scrape

Scrape one URL with selectable content fields and optional internal-link following.

Base URL

Send requests to https://search.venym.io/api with Authorization: Bearer <your-api-key>.

02 · Quick Example

Scrape a Page

Authenticated Scrape 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", "links", "metadata"]
  }'

03 · Parameters

Request Parameters

POST /api/v1/scrape

Parameter	Type	Required	Description
`url`	string	Required	The HTTP or HTTPS URL to scrape. Example: `"https://example.com"`
`extract_options`	array[string]	Optional	Fields to request from the target: title, text, links, images, metadata, or all. Default: ["title", "text"] Example: `["title", "text", "links"]`
`follow_internal_links`	boolean	Optional	Follow and scrape internal links discovered on the primary page. Requires Unicorn. Default: false Example: `true`
`max_pages`	integer	Optional	Maximum discovered internal pages to process when follow_internal_links is true. Allowed range: 1–50. Default: 10 Example: `3`
`include_contacts`	boolean	Optional	Extract contacts from returned page text. Requires Starter or higher. Default: false Example: `true`

Full parameter reference Authentication

04 · Credit Model

Predictable Charges

Basic scrape

5 credits

primary page only

Three internal pages

11 credits

5 + (3 × 2)

Feature gates

No extra tariff

contacts and link following require the matching plan

Scrape reserves the requested internal-page allowance, then refunds pages that do not complete.

05 · Response

Response Format

Scrape response fields

Field	Type	Description
`url`	string	The normalized primary URL.
`primary_content`	object	Structured content returned for the primary page by the execution backend.
`discovered_links`	array	Present only when follow_internal_links is true; contains scraped internal pages.
`links_scraped`	integer	Number of discovered pages completed without an error.
`contacts`	array	Present when include_contacts is true.
`credits_used`	integer	Credits charged after completed work is settled.
`remaining_credits`	integer	Account balance after settlement.
`success`	boolean	True when primary_content has no error.

Successful responseJSON

{
  "url": "https://example.com/",
  "primary_content": {
    "url": "https://example.com/",
    "title": "Example Domain",
    "text": "Example Domain...",
    "links": [],
    "metadata": {},
    "error": null
  },
  "credits_used": 5,
  "remaining_credits": 4995,
  "success": true
}

06 · Status

Response Codes

200Scrape completed; inspect primary_content.error for target-level failures.

400Request validation failed.

401API key is missing or invalid.

402Account does not have enough credits.

403Requested plan-gated feature is unavailable.

429Per-IP Scrape rate limit exceeded; honor Retry-After.

500Unexpected server failure; use request_id when contacting support.

Error responses include code, request_id, timestamp, and documentation_url.

View examples Search API