Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt

Use this file to discover all available pages before exploring further.

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"
​
render_options
object
Fine-grained control over page rendering. Override defaults for wait strategy, timeouts, iframe handling, resource blocking, and retry behavior.Fields:
  • render_type (string) - Wait strategy before returning the response. Options: load (default), domready, idle0, idle2
  • timeout (number) - Maximum time in milliseconds to wait for the page to render.
  • include_iframes (boolean) - Include iframe content in the response.
  • disabled_resources (array) - Resource types to block from loading. Options include image, stylesheet, font, media, script, xhr, fetch, and others.
  • blocked_domains (array) - Domains to block from loading. Useful for filtering ads, trackers, or analytics.
  • skip_network_capture_on_browser_actions_error (boolean) - Stop network capture immediately if a browser action it depends on fails, instead of hanging until the timeout expires.
  • retry_on_network_capture_error (boolean) - Retry the full request if network capture fails, instead of returning a 200 with the capture marked as failed.
  • retry_on_browser_actions_error (boolean) - Retry the full request if a browser action fails, instead of returning success with a failed action.
Example:
"render_options": {
  "render_type": "idle2",
  "timeout": 30000,
  "include_iframes": true,
  "disabled_resources": ["image", "stylesheet"],
  "blocked_domains": ["ads.example.com", "tracker.com"],
  "retry_on_network_capture_error": true
}
​
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(
    url="https://www.example.com",
    referrer_type="google"
)

print(result.data.html)

​
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(
    url="https://api.example.com/created",
    expected_status_codes=[200, 201, 204]
)

print(result.status_code)

​
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(
    url="https://www.example.com",
    http2=True
)

print(result.data.html)

​
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(
    url="https://www.example.com/product/123",
    session={
        "id": "shopping-session-abc",
        "timeout": 600,
        "retry": True
    }
)

print(result.data.html)

​
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(
    url="https://www.example.com",
    tag="campaign-2026-q2"
)

print(result.data.html)

​
Rendering Options

Fine-grained control over how Nimble renders a page before returning the response.
Controls when Nimble considers the page ready before returning the response. Choose based on how the target page loads.
ValueWhen to use
load (default)Waits for the load event — HTML, CSS, images, and all subresources have finished loading.
domreadyFires once the HTML is parsed and the DOM is built, without waiting for images or stylesheets. Fastest option.
idle0Waits until there are 0 in-flight network requests for at least 500ms. Most thorough, but slowest.
idle2Waits 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(
    url="https://www.example.com",
    render_options={"render_type": "idle2"}
)

print(result.data.html)
Sets the maximum milliseconds Nimble waits for the page to render before returning. Default is 30000 (30 seconds). Increase for slow or JS-heavy pages. Decrease to fail fast on unresponsive targets.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render_options={"timeout": 60000}
)

print(result.data.html)
By default, iframe content is excluded from the response. Set to true when the data you need lives inside an embedded frame. Common on finance dashboards, media players, and widget-heavy pages.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render_options={"include_iframes": True}
)

print(result.data.html)
Prevents specific resource types from loading. Reduces render time and bandwidth when you only need the HTML structure. Default is ["image", "font"]. Available types: image, stylesheet, font, media, script, xhr, fetch.
Blocking script prevents JavaScript execution. Only use it on fully static pages.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render_options={"disabled_resources": ["image", "stylesheet", "font"]}
)

print(result.data.html)
Blocks requests to specific third-party domains. Use to suppress ads, trackers, or analytics scripts that slow down rendering or interfere with the response.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render_options={"blocked_domains": ["ads.example.com", "tracker.com"]}
)

print(result.data.html)
When a browser action fails, network capture keeps running until timeout expires. Setting this to true stops capture immediately on action failure, avoiding unnecessary delays.
Only relevant when using browser_actions alongside network_capture.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render=True,
    browser_actions=[
        {"click": {"selector": "button.load-more", "required": True}},
        {"wait": "2s"}
    ],
    network_capture=[
        {
            "url": {"type": "contains", "value": "/api/data"},
            "resource_type": ["xhr", "fetch"]
        }
    ],
    render_options={"skip_network_capture_on_browser_actions_error": True}
)

print(result.data.network_capture)
By default, if network capture fails, Nimble returns a 200 with the capture marked as failed. Set to true to retry the full request instead. Use when capture reliability is critical to your pipeline.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render=True,
    network_capture=[
        {
            "url": {"type": "contains", "value": "/api/data"},
            "resource_type": ["xhr", "fetch"]
        }
    ],
    render_options={"retry_on_network_capture_error": True}
)

print(result.data.network_capture)
By default, if a browser action fails, Nimble returns success with the failed action noted in the response. Set to true to retry the full request instead. Use when browser actions are required for the page to reach the correct state.
from nimble_python import Nimble

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

result = nimble.extract(
    url="https://www.example.com",
    render=True,
    browser_actions=[
        {"click": {"selector": "button.accept-cookies", "required": True}},
        {"wait_for_element": {"selector": ".main-content", "timeout": 5000}}
    ],
    render_options={"retry_on_browser_actions_error": True}
)

print(result.data.html)

​
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(
    url="https://www.example.com",
    device="mobile"
)

print(result.data.html)

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