Create one asynchronous request

Create one asynchronous request

POST
/api/v1/data/requests

Create one asynchronous request

Authorization

headerX-API-Key<token>

Header Parameters

Idempotency-Key?string

Optional. 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.

Length8 <= length <= 200

Request Body

application/json
  1. body
url*string
Formaturi
Lengthlength <= 4096
mode?string

Optional 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.

Value in"direct""auto""browser""http""residential""residential_browser"
geo_country?string

Requested 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.

Length2 <= length <= 2
max_credits_per_request?integer

Hard 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.

Range1 <= value
proxy?string
Default"random"
Value in"random""off"
proxy_type?string

Requested 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.

Value in"datacenter""residential""premium"
headers?

Transport-controlled and hop-by-hop headers are rejected; names and values cannot contain control characters.

Default{}
cookies?

Cookie names and values are validated and cannot contain control characters.

Default{}
timeout_ms?integer
Range5000 <= value <= 300000
Default45000
javascript?boolean
Defaulttrue
resource_policy?string

Browser 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.

Default"adaptive"
Value in"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.

Length1 <= length <= 500
user_agent?|
Length1 <= length <= 1000
result_text_selector?|
Length1 <= length <= 500
wait_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.

Itemsitems <= 20
Default[]
debug_artifacts?boolean

Opt 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.

Defaultfalse
skip_cache?boolean
Defaultfalse
cache_ttl_seconds?integer
Range0 <= value <= 3600
Default300
extraction?|

Response Body

Accepted or idempotently replayed Error body uses the documented PublicError DTO.

application/json
  1. response
id*string
Formatuuid
url?string

Target origin only; path and query are stored in the encrypted short-retention payload.

Formaturi
status*DataJobStatus
Value in"pending""running""solving_captcha""completed""failed""cancelled"
cached*boolean
protected*boolean

True after server-side anti-bot protection detection.

pricing_version*integer
Range1 <= value
route_mode*string
Value in"direct""auto""browser""http""residential""residential_browser""mixed"
proxy_type?ProxyNetworkType

Requested proxy network class. Present on new submissions; historical idempotent replays may omit this field.

Value in"datacenter""residential""premium"
base_tokens*integer
Range0 <= value
protected_tokens*integer

Historical compatibility field; built-in protection is included in the selected pricing-v2 request mode.

Range0 <= value
captcha_tokens*integer
Range0 <= value
quote?|

Provider-neutral admission quote. Null when the guarded pricing policy is disabled.

created_at*string
Formatdate-time
charged_tokens*integer

Base credits charged by this submission operation; dynamic protected/CAPTCHA debits occur later. Zero on an idempotent replay.

Range0 <= value
idempotent_replay*boolean

True only when this response replays a previous submission with the same idempotency key and payload.

result_kind?"extraction"

Present for structured extraction requests.

Value in"extraction"
page_status?string

Underlying 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}