browserSettings, fingerprint, proxy, cookies, waitFor, field, and actions before you start building lets you configure browser tasks, CDP sessions, and cloud browsers consistently and correctly.
browserSettings
Browser configuration shared across CDP sessions and cloud browsers. Omitted regions use a random trusted proxy; explicitly pass GLOBAL, a region code, or a custom proxy object when you need deterministic routing.
Custom proxy configuration. Cannot be combined with
countryCode. See the proxy schema below.Managed proxy region. Use
"GLOBAL" to select a popular region automatically, or a two-letter country code (e.g. "FR") to prefer a trusted proxy in that region with dynamic fallback. Cannot be combined with proxy.Set to
"random" to let the server select a User-Agent from its library. Requests without a User-Agent default to "random".Browser fingerprint settings. When omitted in CDP contexts,
canvas and webGlImage default to "real" while other signals use a coherent randomized profile. See the fingerprint schema below.Cookies injected into the browser context before the session starts. See the
cookies[] schema below.Example
fingerprint
Controls browser fingerprint signals to reduce detectability. Every field is optional. Browser-task omissions default to "random". CDP browserSettings omissions set canvas and webGlImage to "real" and generate other signals from a coherent randomized profile.
Example
proxy
Custom proxy configuration for routing browser traffic. Provide either the server URL form or the split form (protocol + host + port) — never both.
Full proxy URL, e.g.
"http://host:port" or "socks5://host:port". Must include an explicit port. Cannot be combined with host. Do not embed credentials, a path, a query string, or a fragment.Examples
cookies[]
An array of cookies injected into the browser context before navigation begins. Each entry is an object with the following fields.
Persistent expiry as a Unix timestamp in seconds. All three field names are accepted interchangeably.
Example
waitFor
Instructs the browser to pause after navigation or after executing actions until a specific element or text becomes visible on the page. You can combine selector and text in the same object.
Maximum wait time in milliseconds. Defaults to
15000. Never exceeds the remaining task timeout, regardless of the value you supply.Example
field (SPA Extract Field Definition)
Defines a single field to extract in a POST /spa-extract request. DOM fields read element content; network fields capture data from intercepted JSON responses.
Data source for this field. Use
"dom" to read from the page’s DOM, or "network" to capture a matching JSON response from a network request.DOM read mode. Defaults to
"text". Use "html" to get the element’s inner HTML, or "attribute" to read a specific attribute.A substring used to match the response URL for
source: "network" fields. The most recent matching response is used.JSONPath expression to extract a value from the matched network response body. For example,
"$.data.metrics[0].value".When
true, the field returns an array of all matching DOM elements instead of just the first.Coerces the extracted raw value to the specified type before returning it.
A regular expression applied to the extracted value. When the pattern contains a capture group, group 1 is returned as the field value.
When
true, a missing or unmatched field causes the endpoint to return 422 SPA_REQUIRED_FIELDS_MISSING instead of returning null.Examples
actions[]
An ordered array of page interactions executed before extraction begins in POST /spa-extract. Each element is an object with a type field that determines which action runs. Every interactive step is capped at 30 seconds.
wait — pause execution
wait — pause execution
waitForSelector — wait for an element
waitForSelector — wait for an element
click — click an element
click — click an element
fill — fill an input
fill — fill an input
press — press a key
press — press a key
scroll — scroll the page or an element
scroll — scroll the page or an element
Scrolls an element into view, or scrolls the page by a given pixel offset.
Full actions example
cloudBrowser.runtime
The runtime status object returned by cloud browser endpoints. It describes the current lifecycle state of a running or stopped browser session.
The type of runtime backing this browser session.
"neko" provides an interactive browser and omits cdpBaseUrl. "worker_cdp" exposes a CDP endpoint and may include cdpBaseUrl.Direct URL to open the interactive browser. Only present when
status is "running" and runtimeKind is "neko". Requires the profile owner’s login session — authorization uses the session cookie, not the viewer’s usr/pwd URL parameters.Both
"starting" and "stopping" states count against the user’s concurrent running quota. A "stopping" session has not yet released its slot — poll GET /cloud-browsers/{id} until you see "stopped" before assuming capacity is available.Example responses
Google Trends Result Metadata
Additional top-level fields returned alongside the standard SPA result by successfulgoogle-trends-explore responses. These fields describe whether the result was collected live or served from the server cache.
Indicates whether the result was collected from a live browser session (
"sunbrowser") or served from the server-side cache ("cache").true when the cached result is stale. The response was served from cache but the data may be outdated.The timestamp at which the result was actually collected, in RFC3339Nano format.
The number of collection attempts made before the result was returned. Cache HIT responses always report
0. Stale responses report the number of attempts already made when the result was reported.