Advanced Options

Advanced options let you control how Nimble issues requests at a lower level. Use them to tune referrer behavior, accept specific response codes, switch protocols, persist sessions, tag requests, or emulate different device types.

When to use

Use advanced options when you need to:

Control referrer behavior: Set realistic referrers to bypass referrer-based gating
Accept non-200 responses: Treat specific status codes as successful
Switch to HTTP/2: Required by some modern sites for correct responses
Persist sessions: Reuse the same browser session across requests
Tag requests: Attach a label for tracking or analytics
Emulate devices: Render pages as mobile or tablet instead of desktop

These are advanced parameters. Misconfiguring them can cause requests to fail or trigger anti-bot detection.

Parameters

referrer_type

string

Referrer policy for the request. Nimble sends the chosen referrer header with the request to mimic real browsing behavior.Generic policies:

random - Use a randomly selected referrer
no-referrer - Do not send any referrer
same-origin - Use the target site’s own origin as referrer

Search and social referrers:

google, bing - Search engine referrers
facebook, twitter, instagram - Social platform referrers

Example:

"referrer_type": "google"

expected_status_codes

array

HTTP status codes that should be treated as successful. By default, only 200 is considered success. Use this to accept responses like 201 (Created), 204 (No Content), or 302 (Redirect).Format: Array of integers.

Example:

"expected_status_codes": [200, 201, 204]

http2

boolean

default:"false"

Use HTTP/2 instead of HTTP/1.1 for the request. Some sites require HTTP/2 to return the expected response.

Example:

"http2": true

session

object

Persist a browser session across multiple requests. Useful for maintaining login state, cookies, or navigation context between calls.Fields:

id (string) - Session identifier. Reuse the same ID across requests to share the session.
timeout (number) - Session timeout in seconds. Must be greater than 0.
retry (boolean, default false) - Retry the request within the same session on failure.
prefetch_userbrowser (boolean, default false) - Preload the user browser for faster subsequent requests.

Example:

"session": {
  "id": "my-session-123",
  "timeout": 300,
  "retry": true,
  "prefetch_userbrowser": true
}

tag

string

User-defined label attached to the request. Use tags to group requests by campaign, workflow, or customer for tracking and analytics.

Example:

"tag": "campaign-2026-q2"

request_timeout

number

Maximum time in milliseconds to wait for the request to complete. Increase for slow or JS-heavy pages; decrease to fail fast on unresponsive targets.

Example:

"request_timeout": 60000

device

string

default:"desktop"

Device type for browser emulation. Affects viewport size, user agent, and rendering behavior.Options: desktop | mobile | tablet

Example:

"device": "mobile"

Usage

Set a referrer

Send a Google referrer to mimic search engine traffic.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com",
    referrer_type="google"
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com",
  referrer_type: "google",
});

console.log(result.data.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com",
    "referrer_type": "google"
}'

nimble extract run \
  --url "https://www.example.com" \
  --referrer-type google

Accept multiple status codes

Treat 200, 201, and 204 all as successful responses.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://api.example.com/created",
    expected_status_codes=[200, 201, 204]
)

print(result.status_code)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://api.example.com/created",
  expected_status_codes: [200, 201, 204],
});

console.log(result.status_code);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://api.example.com/created",
    "expected_status_codes": [200, 201, 204]
}'

nimble extract run \
  --url "https://api.example.com/created" \
  --expected-status-code 200 --expected-status-code 201 --expected-status-code 204

Force HTTP/2

Force the request to use HTTP/2 instead of HTTP/1.1.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com",
    http2=True
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com",
  http2: true,
});

console.log(result.data.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com",
    "http2": true
}'

nimble extract run \
  --url "https://www.example.com" \
  --http2 true

Persist a session

Reuse a browser session across multiple requests.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com/product/123",
    session={
        "id": "shopping-session-abc",
        "timeout": 600,
        "retry": True
    }
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com/product/123",
  session: {
    id: "shopping-session-abc",
    timeout: 600,
    retry: true,
  },
});

console.log(result.data.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com/product/123",
    "session": {
      "id": "shopping-session-abc",
      "timeout": 600,
      "retry": true
    }
}'

nimble extract run \
  --url "https://www.example.com/product/123" \
  --session '{id: shopping-session-abc, timeout: 600, retry: true}'

Tag a request

Attach a label to the request for tracking.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com",
    tag="campaign-2026-q2"
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com",
  tag: "campaign-2026-q2",
});

console.log(result.data.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com",
    "tag": "campaign-2026-q2"
}'

nimble extract run \
  --url "https://www.example.com" \
  --tag "campaign-2026-q2"

Set a wait strategy

Control when Nimble considers the page ready with a wait_for_navigation browser action:

Value	When to use
`load` (default)	Waits for the load event — HTML, CSS, images, and all subresources have finished loading.
`domcontentloaded`	Fires once the HTML is parsed and the DOM is built, without waiting for images or stylesheets. Fastest option.
`networkidle0`	Waits until there are 0 in-flight network requests for at least 500ms. Most thorough, but slowest.
`networkidle2`	Waits until there are 2 or fewer in-flight network requests for at least 500ms. Good for pages with lazy-loaded content.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com",
    render=True,
    browser_actions=[{"wait_for_navigation": "networkidle2"}]
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com",
  render: true,
  browser_actions: [{ wait_for_navigation: "networkidle2" }],
});

console.log(result.data?.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{"url": "https://www.example.com", "render": true, "browser_actions": [{"wait_for_navigation": "networkidle2"}]}'

nimble extract run \
  --url "https://www.example.com" \
  --render true \
  --browser-action '{wait_for_navigation: "networkidle2"}'

Limit request time

Cap how long Nimble waits for the request with request_timeout (milliseconds):

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com",
    request_timeout=60000
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com",
  request_timeout: 60000,
});

console.log(result.data?.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{"url": "https://www.example.com", "request_timeout": 60000}'

nimble extract run \
  --url "https://www.example.com" \
  --request-timeout 60000

Emulate a device

Render the page as a mobile device.

from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract.run(
    url="https://www.example.com",
    device="mobile"
)

print(result.data.html)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.extract.run({
  url: "https://www.example.com",
  device: "mobile",
});

console.log(result.data.html);

curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com",
    "device": "mobile"
}'

nimble extract run \
  --url "https://www.example.com" \
  --device mobile

Custom Headers & Cookies

Send custom request headers and cookies

Geo-Targeting

Route requests through specific countries, states, or cities

Stealth Mode

Bypass anti-bot detection with real user emulation

JS Rendering

Render JavaScript-heavy pages before extraction

Getting Started

Web Search

Search Agent

Extraction Tools

Extraction Templates

Jobs

Guides

SDKs

Admin

Proxy

When to use

Parameters

Usage

Set a referrer

Accept multiple status codes

Force HTTP/2

Persist a session

Tag a request

Set a wait strategy

Limit request time

Emulate a device

Custom Headers & Cookies

Geo-Targeting

Stealth Mode

JS Rendering

​When to use

​Parameters

​Usage

​Set a referrer

​Accept multiple status codes

​Force HTTP/2

​Persist a session

​Tag a request

​Set a wait strategy

​Limit request time

​Emulate a device

​Related

Custom Headers & Cookies

Geo-Targeting

Stealth Mode

JS Rendering

When to use

Parameters

Usage

Set a referrer

Accept multiple status codes

Force HTTP/2

Persist a session

Tag a request

Set a wait strategy

Limit request time

Emulate a device

Related