Search Parameters
The complete request and response contract for POST /api/v1/search.
400 response.Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Required | Non-empty search query. Whitespace is trimmed and the value is limited to 1,000 characters. Example: |
max_results | integer | Optional | Maximum ranked results to return. Allowed range: 1–50. Default: 10 Example: |
auto_scrape_top | integer | Optional | Automatically scrape the first N result URLs. Allowed range: 0–10. Default: 0 Example: |
include_contacts | boolean | Optional | Extract contacts from automatic scrape results. Requires Starter or higher. Default: false Example: |
include_social | boolean | Optional | Extract social profiles from automatic scrape results. Requires Builder or higher. Default: false Example: |
Credit Calculation
auto_scrape_top: 3, the maximum reservation is 11 credits (2 + 3 × 3). Failed scrape pages are refunded after settlement.Response Fields
| Field | Type | Description |
|---|---|---|
query | string | Normalized query that was executed. |
search_results | array | Ranked objects containing title, link, snippet, position, and optional date. |
scraped_content | array | Automatic scrape results, including target-level errors when a page fails. |
contacts | array | Included only when include_contacts is true. |
social_profiles | array | Included only when include_social is true. |
credits_used | integer | Final charge after completed work is settled. |
remaining_credits | integer | Account balance after the request. |
results_count | integer | Number of returned search results. |
scraped_count | integer | Number of automatic pages completed without an error. |
Valid Request
curl -X POST https://search.venym.io/api/v1/search \
-H "Authorization: Bearer $VENYM_SEARCH_API_KEY" \
-H "Content-Type: application/json" \
--data '{"query":"latest AI developments","max_results":10}'A valid API key can call Search. include_contacts requires Starter or higher; include_social requires Builder or higher. These failures return 403, not 400.