API Schema Reference — Shared Types for All Endpoints

These schemas appear across multiple AdsCrawl endpoints. Instead of repeating field definitions in every endpoint reference, this page documents each schema once. Understanding 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.

object

Browser window size.

Show viewport fields

number

required

Viewport width in pixels.

number

required

Viewport height in pixels.

string

Browser locale, such as "en-US".

string

IANA timezone identifier, such as "Asia/Shanghai".

object

Optional geolocation coordinates to inject into the browser.

Show geolocation fields

number

required

Latitude in decimal degrees.

number

required

Longitude in decimal degrees.

object

Custom proxy configuration. Cannot be combined with countryCode. See the proxy schema below.

string

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.

string

Overrides the default User-Agent string.

"custom" | "random"

Set to "random" to let the server select a User-Agent from its library. Requests without a User-Agent default to "random".

"windows" | "macos"

Operating system used by random User-Agent mode. Defaults to "windows".

object

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[]

Cookies injected into the browser context before the session starts. See the cookies[] schema below.

Example

{
  "viewport": { "width": 1440, "height": 900 },
  "locale": "en-US",
  "timezoneId": "America/New_York",
  "countryCode": "US",
  "userAgentMode": "random",
  "userAgentOs": "macos",
  "fingerprint": {
    "canvas": "random",
    "webRtc": "forward"
  }
}

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

When webGl is "real", you cannot set webGpu or hardware to "random". These three signals must be consistent with each other.

Field	Accepted Values	Notes
`webRtc`	`"forward"` \| `"real"` \| `"disabled"`	`"forward"` uses the proxy exit address. The legacy value `"random"` is accepted as an alias for `"forward"`.
`webGl`	`"random"` \| `"real"`	Spoofs or preserves WebGL vendor and renderer metadata.
`webGpu`	`"random"` \| `"real"` \| `"disabled"`	In `"random"` mode, follows the WebGL GPU configuration.
`webGlImage`	`"random"` \| `"real"`	Controls WebGL image rendering noise.
`canvas`	`"random"` \| `"real"`	Adds or suppresses canvas fingerprint noise.
`audioContext`	`"random"` \| `"real"`	Adds or suppresses audio context fingerprint noise.
`clientRects`	`"random"` \| `"real"`	Adds or suppresses layout measurement noise.
`speechVoices`	`"random"` \| `"real"`	Returns an OS-matched or real speech voice list.
`fonts`	`"random"` \| `"real"`	Returns an OS-matched or real installed font list.
`hardware`	`"random"` \| `"real"`	Generates CPU thread count and device memory as a matched pair.
`doNotTrack`	`"random"` \| `"enabled"` \| `"disabled"`	Controls the DNT request header preference.

Example

{
  "webRtc": "forward",
  "webGl": "random",
  "webGpu": "random",
  "canvas": "random",
  "audioContext": "random",
  "fonts": "random",
  "hardware": "random",
  "doNotTrack": "disabled"
}

`proxy`

Custom proxy configuration for routing browser traffic. Provide either the server URL form or the split form (protocol + host + port) — never both.

Supply username and password together. Omit both for an unauthenticated proxy. Never embed credentials in the server URL.

string

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.

"http" | "socks5"

Proxy protocol for the split form.

string

Proxy hostname for the split form. Cannot be combined with server.

number | string

Proxy port for the split form. Accepts an integer or numeric string from 1 to 65535.

string

Proxy authentication username. Must be supplied together with password.

string

Proxy authentication password. Must be supplied together with username.

Examples

{
  "server": "http://proxy.example.com:8080",
  "username": "<proxy-user>",
  "password": "<proxy-password>"
}

{
  "protocol": "socks5",
  "host": "proxy.example.com",
  "port": 1080,
  "username": "<proxy-user>",
  "password": "<proxy-password>"
}

{
  "server": "http://proxy.example.com:8080"
}

`cookies[]`

An array of cookies injected into the browser context before navigation begins. Each entry is an object with the following fields.

string

required

Cookie name.

string

required

Cookie value.

string

required

Target domain, e.g. ".example.com". Include the leading dot to match subdomains.

string

Cookie path. Defaults to "/".

boolean

When true, the cookie is sent only over HTTPS.

boolean

When true, the cookie is inaccessible to client-side JavaScript.

boolean

When true, the cookie is bound to the exact host and not subdomains.

string

SameSite attribute. Accepted values: "Strict", "Lax", "None".

boolean

When true, the cookie expires with the session and has no persistent expiry.

number

Persistent expiry as a Unix timestamp in seconds. All three field names are accepted interchangeably.

Example

[
  {
    "name": "sid",
    "value": "<session-token>",
    "domain": ".example.com",
    "path": "/",
    "secure": true,
    "httpOnly": true,
    "sameSite": "Lax",
    "expirationDate": 1893456000
  }
]

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

string

CSS selector. The browser waits for the first matching element to become visible.

string

Text content. The browser waits for the first element containing this text to become visible.

number

Maximum wait time in milliseconds. Defaults to 15000. Never exceeds the remaining task timeout, regardless of the value you supply.

Example

{
  "selector": "#search-results",
  "timeoutMs": 10000
}

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

"dom" | "network"

required

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.

string

CSS selector identifying the target element. Required for source: "dom" fields.

"text" | "html" | "attribute"

DOM read mode. Defaults to "text". Use "html" to get the element’s inner HTML, or "attribute" to read a specific attribute.

string

The attribute name to read when value is "attribute". For example, "href" or "data-id".

string

A substring used to match the response URL for source: "network" fields. The most recent matching response is used.

string

JSONPath expression to extract a value from the matched network response body. For example, "$.data.metrics[0].value".

boolean

When true, the field returns an array of all matching DOM elements instead of just the first.

"string" | "number" | "integer" | "boolean" | "json"

Coerces the extracted raw value to the specified type before returning it.

string

A regular expression applied to the extracted value. When the pattern contains a capture group, group 1 is returned as the field value.

boolean

When true, a missing or unmatched field causes the endpoint to return 422 SPA_REQUIRED_FIELDS_MISSING instead of returning null.

Examples

{
  "source": "dom",
  "selector": "h1.product-title",
  "value": "text",
  "required": true
}

{
  "source": "dom",
  "selector": "meta[name='description']",
  "value": "attribute",
  "attribute": "content"
}

{
  "source": "network",
  "urlIncludes": "/api/v2/metrics",
  "path": "$.data.metrics[0].value",
  "parse": "number",
  "required": true
}

{
  "source": "dom",
  "selector": "ul.results li",
  "value": "text",
  "multiple": true
}

`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

Pauses execution for a fixed number of milliseconds.

{ "type": "wait", "milliseconds": 2000 }

string

required

Must be "wait".

number

required

Duration to pause. Accepted range: 0 to 30000.

waitForSelector — wait for an element

Pauses until the first element matching the CSS selector becomes visible.

{ "type": "waitForSelector", "selector": "#content", "timeoutMs": 8000 }

string

required

Must be "waitForSelector".

string

required

CSS selector to wait for.

number

Maximum wait in milliseconds. Defaults to the step’s 30-second cap when omitted.

click — click an element

Clicks the first element matching the CSS selector.

{ "type": "click", "selector": "button.load-more" }

string

required

Must be "click".

string

required

CSS selector of the element to click.

fill — fill an input

Clears the target input element and types the given value into it.

{ "type": "fill", "selector": "input[name='q']", "value": "browser automation" }

string

required

Must be "fill".

string

required

CSS selector of the input element to fill.

string

required

Text to enter into the input.

press — press a key

Sends a keyboard key press to the first element matching the CSS selector.

{ "type": "press", "selector": "input[name='q']", "key": "Enter" }

string

required

Must be "press".

string

required

CSS selector of the target element.

string

required

Key to press, such as "Enter", "Tab", or "ArrowDown".

scroll — scroll the page or an element

Scrolls an element into view, or scrolls the page by a given pixel offset.

{ "type": "scroll", "y": 1200 }

{ "type": "scroll", "selector": ".lazy-section" }

string

required

Must be "scroll".

string

CSS selector. When provided, the matching element is scrolled into view.

number

Horizontal scroll offset in pixels. Defaults to 0.

number

Vertical scroll offset in pixels. Defaults to 800 when no selector is given.

Full actions example

[
  { "type": "waitForSelector", "selector": "#cookie-banner button", "timeoutMs": 5000 },
  { "type": "click", "selector": "#cookie-banner button" },
  { "type": "fill", "selector": "input[name='q']", "value": "adscrawl api" },
  { "type": "press", "selector": "input[name='q']", "key": "Enter" },
  { "type": "waitForSelector", "selector": "#results", "timeoutMs": 10000 },
  { "type": "scroll", "y": 1600 }
]

`cloudBrowser.runtime`

The runtime status object returned by cloud browser endpoints. It describes the current lifecycle state of a running or stopped browser session.

Never construct connectUrl or cdpBaseUrl yourself, and never append API keys, cookies, or proxy credentials to these URLs. Always use the exact URLs returned by the API. If a URL is absent from the response, query the current status before proceeding.

"neko" | "worker_cdp"

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.

"starting" | "running" | "stopping" | "stopped"

required

The current lifecycle status of the session.

Show Status values

Value	Meaning
`starting`	Session is being provisioned. Running quota is already reserved.
`running`	Session is active. `connectUrl` may be present.
`stopping`	A stop was requested but is not yet confirmed. Running quota is still reserved.
`stopped`	Session has ended. Running quota is released.

string

The active session identifier. Present for starting, running, and stopping states.

string (RFC3339)

The time at which the active session expires.

string

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.

string

The CDP base URL with a temporary token. Only returned by worker_cdp runtimes.

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

{
  "runtimeKind": "neko",
  "status": "running",
  "sessionId": "<session-id>",
  "expiresAt": "2026-09-07T09:00:00.000Z",
  "connectUrl": "https://api.adscrawl.net/cloud-browser-runtime/<session-id>/?usr=adscrawl&pwd=adscrawl"
}

{
  "runtimeKind": "neko",
  "status": "stopped"
}

{
  "runtimeKind": "neko",
  "status": "stopping",
  "sessionId": "<session-id>",
  "expiresAt": "2026-09-07T09:00:00.000Z"
}

Google Trends Result Metadata

Additional top-level fields returned alongside the standard SPA result by successful google-trends-explore responses. These fields describe whether the result was collected live or served from the server cache.

"sunbrowser" | "cache"

required

Indicates whether the result was collected from a live browser session ("sunbrowser") or served from the server-side cache ("cache").

boolean

required

true when this response was served from the cache.

boolean

required

true when the cached result is stale. The response was served from cache but the data may be outdated.

string (RFC3339Nano)

required

The timestamp at which the result was actually collected, in RFC3339Nano format.

integer

required

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.

Example

{
  "source": "sunbrowser",
  "cached": false,
  "stale": false,
  "collectedAt": "2026-09-07T08:42:11.348291200Z",
  "attempts": 1
}

Overview

Browser Tasks

Remote CDP

Cloud Browsers

API Schema Reference — Shared Types for All Endpoints

`browserSettings`

Example

`fingerprint`

Example

`proxy`

Examples

`cookies[]`

Example

`waitFor`

Example

`field` (SPA Extract Field Definition)

Examples

`actions[]`

Full actions example

`cloudBrowser.runtime`

Example responses

Google Trends Result Metadata

Example

​browserSettings

​Example

​fingerprint

​Example

​proxy

​Examples

​cookies[]

​Example

​waitFor

​Example

​field (SPA Extract Field Definition)

​Examples

​actions[]

​Full actions example

​cloudBrowser.runtime

​Example responses

​Google Trends Result Metadata

​Example

`browserSettings`

Example

`fingerprint`

Example

`proxy`

Examples

`cookies[]`

Example

`waitFor`

Example

`field` (SPA Extract Field Definition)

Examples

`actions[]`

Full actions example

`cloudBrowser.runtime`

Example responses

Google Trends Result Metadata

Example