Custom Headers & Cookies

Custom headers and cookies enable you to access personalized data, maintain user sessions, and interact with authenticated endpoints. Set headers and cookies in string or object format to mimic real user behavior and retrieve content that requires specific request contexts.

When to use

Use custom headers and cookies when you need to:

Access authenticated content: Retrieve data behind login walls
Maintain sessions: Preserve user state across requests
Mimic real users: Include user-specific headers for personalized data
API authentication: Send API keys or tokens in headers
Regional content: Set language or region preferences

This is an advanced feature. Misconfigured headers or cookies may trigger anti-bot detection or cause requests to fail.

Parameters

headers

object

Add custom HTTP headers to your request. Useful for authentication, setting custom user agents, or mimicking specific browsers.Common use cases:

API authentication (API keys, tokens)
Custom User-Agent strings
Accept-Language preferences
Referer headers
Custom authentication headers

Format: Provide headers as key-value pairs in an object.

Example:

"headers": {
  "User-Agent": "MyApp/1.0",
  "Accept-Language": "en-US,en;q=0.9",
  "X-API-Key": "your-api-key"
}

method

string

default:"GET"

The HTTP method to use for the request.Supported methods: GET, POST, PUT, DELETE, PATCHWhen to use:

GET - Fetching data (default)
POST - Submitting forms or data
PUT - Updating resources
DELETE - Removing resources

Note: When using POST or PUT, you’ll typically also need to include a body parameter.

Example:

"method": "POST"

body

object

The data to send in the request body. Used with POST, PUT, or PATCH requests.Format: Can be an object (auto-converted to JSON) or a string.Common uses:

Form submissions
API payloads
Search queries
Data uploads

Example:

"method": "POST",
"body": {
  "query": "product search",
  "filters": ["category:electronics"]
}

cookies (string format)

string

Send cookies as a simple string, just like they appear in the browser. Separate multiple cookies with semicolons.When to use:

Quickest way to add cookies
When you have a cookie string from browser dev tools
Session IDs and authentication tokens

Format: name1=value1;name2=value2;name3=value3

Example:

"cookies": "session_id=abc123xyz;user_pref=en_US;logged_in=true"

cookies (array format)

array

Send cookies as an array of objects for more control. Each cookie can specify its domain.When to use:

Different cookies for different domains
More precise cookie control
Complex cookie setups

Each cookie object needs:

key - Cookie name (required)
value - Cookie value (required)
domain - Cookie domain (optional, defaults to request URL domain)

Example:

"cookies": [
  {
    "key": "session_id",
    "value": "abc123xyz",
    "domain": "example.com"
  },
  {
    "key": "user_token",
    "value": "token456",
    "domain": "api.example.com"
  }
]

Headers and cookies cannot be used together. Please do not include any cookies when sending custom headers.\ \ Just remember that cookies can be provided in either string format OR array format, but not both at the same time.

Usage

Send custom headers

Include headers as an object:

from nimble_python import Nimble

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

result = nimble.extract(
    url= "https://api.example.com/data",
    headers= {
        "User-Agent": "MyApp/1.0",
        "Accept-Language": "en-US,en;q=0.9",
		"Some-Extra-Header": "some-extra-header"
    }
)

print(result)

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

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

const result = await nimble.extract({
  url: "https://api.example.com/data",
  headers: {
    "User-Agent": "MyApp/1.0",
    "Accept-Language": "en-US,en;q=0.9",
    "Some-Extra-Header": "some-extra-header",
  },
});

console.log(result);

curl -X POST 'https://sdk.nimbleway.com/v1/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://api.example.com/data",
    "headers": {
        "User-Agent": "MyApp/1.0",
        "Accept-Language": "en-US,en;q=0.9",
		"Some-Extra-Header": "some-extra-header"
    }
}'

POST requests with headers

Send POST requests with custom headers and body:

from nimble_python import Nimble

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

result = nimble.extract(
    url= "https://api.example.com/submit",
    method= "POST",
    headers= {
        "Content-Type": "application/json",
        "Some-Extra-Header": "some-extra-header"
    },
    body= {
        "query": "product search",
        "filters": ["category:electronics"]
    }
)

print(result)

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

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

const result = await nimble.extract({
  url: "https://api.example.com/submit",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Some-Extra-Header": "some-extra-header",
  },
  body: {
    query: "product search",
    filters: ["category:electronics"],
  },
});

console.log(result);

curl -X POST 'https://sdk.nimbleway.com/v1/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://api.example.com/submit",
    "method": "POST",
    "headers": {
        "Content-Type": "application/json",
        "Some-Extra-Header": "some-extra-header"
    },
    "body": {
        "query": "product search",
        "filters": ["category:electronics"]
    }
}'

Send cookies (string format)

Use simple string format for multiple cookies:

from nimble_python import Nimble

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

result = nimble.extract(
    url= "https://www.example.com/account",
    cookies= "session_id=abc123xyz;user_pref=en_US;logged_in=true"
)

print(result)

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

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

const result = await nimble.extract({
  url: "https://www.example.com/account",
  cookies: "session_id=abc123xyz;user_pref=en_US;logged_in=true",
});

console.log(result);

curl -X POST 'https://sdk.nimbleway.com/v1/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com/account",
    "cookies": "session_id=abc123xyz;user_pref=en_US;logged_in=true"
}'

Send cookies (object format)

Use object format for domain-specific cookies:

from nimble_python import Nimble

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

result = nimble.extract(
    url= "https://www.example.com/dashboard",
    cookies= [
        {
            "key": "session_id",
            "value": "abc123xyz",
            "domain": "example.com"
        },
        {
            "key": "user_token",
            "value": "token456",
            "domain": "api.example.com"
        }
    ]
)

print(result)

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

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

const result = await nimble.extract({
  url: "https://www.example.com/dashboard",
  cookies: [
    {
      key: "session_id",
      value: "abc123xyz",
      domain: "example.com",
    },
    {
      key: "user_token",
      value: "token456",
      domain: "api.example.com",
    },
  ],
});

console.log(result);

curl -X POST 'https://sdk.nimbleway.com/v1/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com/dashboard",
    "cookies": [
        {
            "key": "session_id",
            "value": "abc123xyz",
            "domain": "example.com"
        },
        {
            "key": "user_token",
            "value": "token456",
            "domain": "api.example.com"
        }
    ]
}'

Capture cookies with browser actions and reuse

Use browser actions to interact with a page (like selecting a zip code), capture the resulting cookies, and pass them to subsequent requests:

from nimble_python import Nimble

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

# Step 1: Perform browser actions and capture cookies
initial_result = nimble.extract(
    url= "https://www.example.com",
    render= True,
    browser_actions= [
        {
            "click": {
                "selector": "#location-selector"
            }
        },
        {
            "fill": {
                "selector": "#zipcode-input",
                "text": "90210"
            }
        },
        {
            "click": {
                "selector": "#submit-location"
            }
        },
        {
            "wait": 2000
        },
        {
            "get_cookies": True
        }
    ]
)

# Extract cookies from the response
captured_cookies = initial_result.data.cookies

# Step 2: Use captured cookies in subsequent requests
# Convert cookies array to string format
cookie_string = ";".join([f"{cookie['name']}={cookie['value']}" for cookie in captured_cookies])

result = nimble.extract(
    url= "https://www.example.com/products",
    cookies= cookie_string
)

print(result)

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

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

// Step 1: Perform browser actions and capture cookies
const initialResult = await nimble.extract({
  url: "https://www.example.com",
  render: true,
  browser_actions: [
    {
      click: {
        selector: "#location-selector",
      },
    },
    {
      fill: {
        selector: "#zipcode-input",
        text: "90210",
      },
    },
    {
      click: {
        selector: "#submit-location",
      },
    },
    {
      wait: 2000,
    },
    {
      get_cookies: true,
    },
  ],
});

// Extract cookies from the response
const capturedCookies = initialResult.data.cookies;

// Step 2: Use captured cookies in subsequent requests
// Convert cookies array to string format
const cookieString = capturedCookies
  .map((cookie) => `${cookie.name}=${cookie.value}`)
  .join(";");

const result = await nimble.extract({
  url: "https://www.example.com/products",
  cookies: cookieString,
});

console.log(result);

# Step 1: Perform browser actions and capture cookies
curl -X POST 'https://sdk.nimbleway.com/v1/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com",
    "render": true,
    "browser_actions": [
        {
            "click": {
                "selector": "#location-selector"
            }
        },
        {
            "fill": {
                "selector": "#zipcode-input",
                "text": "90210"
            }
        },
        {
            "click": {
                "selector": "#submit-location"
            }
        },
        {
            "wait": 2000
        },
        {
            "get_cookies": true
        }
    ]
}'

# Response will include cookies in data.cookies array:
# {
#   "status": "success",
#   "data": {
#     "html": "...",
#     "cookies": [
#       {
#         "name": "location_zipcode",
#         "value": "90210",
#         "domain": ".example.com"
#       },
#       {
#         "name": "session_id",
#         "value": "abc123xyz",
#         "domain": ".example.com"
#       }
#     ]
#   }
# }

# Step 2: Use captured cookies in subsequent requests
curl -X POST 'https://sdk.nimbleway.com/v1/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://www.example.com/products",
    "cookies": "location_zipcode=90210;session_id=abc123xyz"
}'

This workflow is useful when you need to set user preferences (like location, language, or filters) via browser interaction, then make multiple faster requests with the same session state. See Browser Actions for more interaction options.

Important constraints

Don’t mix headers and cookies:

# ❌ Don't send both in same request
result = nimble.extract({
    "url": "https://www.example.com",
    "headers": {"Some-Extra-Header": "some-extra-header"},
    "cookies": "session_id=abc"  # May cause conflicts
})

# ✅ Use one method
result = nimble.extract({
    "url": "https://www.example.com",
    "headers": {"Some-Extra-Header": "some-extra-header"}
})

Detection risk:

Improper headers may trigger anti-bot detection
Invalid cookies can cause request failures
Test thoroughly before production use
Monitor success rates when using custom headers/cookies

Header size limits:

Total header size: 32 KB
Individual header: 8 KB
Cookie header: 4 KB

This is an advanced feature requiring careful configuration. Always test in a development environment first.

Introduction

Web Search Agents

Web Tools

Guides

SDKs

Admin

Custom Headers & Cookies

When to use

Parameters

Usage

Send custom headers

POST requests with headers

Send cookies (string format)

Send cookies (object format)

Capture cookies with browser actions and reuse

Important constraints

​When to use

​Parameters

​Usage

​Send custom headers

​POST requests with headers

​Send cookies (string format)

​Send cookies (object format)

​Capture cookies with browser actions and reuse

​Important constraints

When to use

Parameters

Usage

Send custom headers

POST requests with headers

Send cookies (string format)

Send cookies (object format)

Capture cookies with browser actions and reuse

Important constraints