Create one asynchronous request
Create one asynchronous request
Create one asynchronous request
X-API-Key<token>Idempotency-Key?stringOptional. Generate a unique value before a write and retain it for an exact-body retry; replay is free and a different body returns 409 IDEMPOTENCY_CONFLICT.
8 <= length <= 200application/json- body
url*stringurilength <= 4096mode?stringOptional route mode. When omitted, javascript=true resolves to browser and javascript=false resolves to http. direct uses bounded HTTP, auto uses HTTP then browser rendering, and browser starts in the browser. http, residential, and residential_browser remain supported explicit route modes. direct and http use the selected network class's HTTP tariff, browser uses its browser tariff, residential uses the residential HTTP tariff, and residential_browser uses the residential browser tariff. auto bills the terminal HTTP or browser stage after execution.
"direct""auto""browser""http""residential""residential_browser"geo_country?stringRequested ISO 3166-1 alpha-2 proxy exit country; input is normalized to uppercase. The effective proxy route is verified before the target is requested; browser contexts then apply timezone/geolocation. An unavailable or mismatched route fails with PROXY_GEO_VERIFICATION_FAILED.
2 <= length <= 2max_credits_per_request?integerHard ceiling for total credits charged to this newly accepted request. It includes HTTP or browser execution, CAPTCHA and measured traffic from a successful result. The limit is shared by immediate and deferred billing stages. If execution must stop before producing a complete result, the request ends with budget_exhausted.
1 <= valueproxy?string"random""random""off"proxy_type?stringRequested proxy network type. If omitted, the route mode determines the legacy default. This selects the datacenter, residential or premium tariff independently of transport mode. Premium requires explicit selection, a configured plan price and an available connection, and cannot be combined with proxy off. Provider selection and tariff resolution are internal and are not returned in public responses.
"datacenter""residential""premium"headers?Transport-controlled and hop-by-hop headers are rejected; names and values cannot contain control characters.
{}cookies?Cookie names and values are validated and cannot contain control characters.
{}timeout_ms?integer5000 <= value <= 30000045000javascript?booleantrueresource_policy?stringBrowser resource loading policy. adaptive starts in full mode, promotes back to full on challenges, and switches to site-light only after the page is usable. site-light blocks media, images, manifests and a conservative known advertising/analytics denylist while preserving documents, scripts, XHR/fetch, WASM, service workers, styles and fonts. compatible always uses full mode; adaptive enables site-light only after the page is usable.
"adaptive""compatible""adaptive"wait_for_selector?|CSS selector that must appear when supplied; if it does not appear before min(timeout_ms, 30000), the job fails.
1 <= length <= 500user_agent?|1 <= length <= 1000result_text_selector?|1 <= length <= 500wait_for_text?null|browser_actions?array<||>Ordered, declarative browser-only actions. Any non-empty list promotes HTTP routes to their browser equivalent, enables JavaScript, uses a fresh isolated browser context, and bypasses the result cache. The full ordered list is persisted for a request retry and returned by clone-input. A click that changes the page URL, opens a popup, or starts a download is blocked. Only aggregate action diagnostics are included in result_meta.
items <= 20[]debug_artifacts?booleanOpt in to short-lived, encrypted, tenant-private diagnostics only if the request terminally fails. Enabling it promotes HTTP routes to browser execution, enables JavaScript, uses an isolated context, and bypasses cache. Diagnostics exclude page HTML, response bodies, headers, cookies, credentials, and raw browser traces; the screenshot endpoint may show target-page content despite masked known form controls.
falseskip_cache?booleanfalsecache_ttl_seconds?integer0 <= value <= 3600300extraction?|Accepted or idempotently replayed Error body uses the documented PublicError DTO.
application/json- response
id*stringuuidurl?stringTarget origin only; path and query are stored in the encrypted short-retention payload.
uristatus*DataJobStatus"pending""running""solving_captcha""completed""failed""cancelled"cached*booleanprotected*booleanTrue after server-side anti-bot protection detection.
pricing_version*integer1 <= valueroute_mode*string"direct""auto""browser""http""residential""residential_browser""mixed"proxy_type?ProxyNetworkTypeRequested proxy network class. Present on new submissions; historical idempotent replays may omit this field.
"datacenter""residential""premium"base_tokens*integer0 <= valueprotected_tokens*integerHistorical compatibility field; built-in protection is included in the selected pricing-v2 request mode.
0 <= valuecaptcha_tokens*integer0 <= valuequote?|Provider-neutral admission quote. Null when the guarded pricing policy is disabled.
created_at*stringdate-timecharged_tokens*integerBase credits charged by this submission operation; dynamic protected/CAPTCHA debits occur later. Zero on an idempotent replay.
0 <= valueidempotent_replay*booleanTrue only when this response replays a previous submission with the same idempotency key and payload.
result_kind?"extraction"Present for structured extraction requests.
"extraction"page_status?stringUnderlying page-fetch status for extraction requests; top-level status tracks extraction readiness.
curl -X POST 'https://api.runharvester.com/api/v1/data/requests' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://example.com", "mode": "auto", "proxy": "random", "proxy_type": "datacenter"}' \ --header "X-API-Key: ${RUNHARVESTER_API_KEY:?Set your Data API key}" \ --header "Idempotency-Key: ${RUNHARVESTER_IDEMPOTENCY_KEY:?Set a unique key for this submission; reuse it for retries}"{ "id": "9a20bd58-ed33-4a5b-b63f-b52bb1a62248", "url": "https://example.com", "status": "pending", "cached": false, "protected": false, "pricing_version": 2, "route_mode": "http", "base_tokens": 1, "protected_tokens": 0, "captcha_tokens": 0, "created_at": "2026-08-22T12:00:00.000Z", "charged_tokens": 1, "idempotent_replay": false}