Skip to main content
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.

​
Supported Parameters

​
Headers

ParameterTypeDescriptionRequired
headersObject or StringCustom HTTP headers to send with requestNo
methodStringHTTP method: GET, POST, PUT, DELETE, etc.When using POST/PUT
bodyString or ObjectRequest body for POST/PUT requestsWhen using POST/PUT

​
Cookies

ParameterTypeDescriptionRequired
cookiesString or ArrayCookies to include in requestNo
cookies[].keyStringCookie nameYes (when using array)
cookies[].valueStringCookie valueYes (when using array)
cookies[].domainStringCookie domain (defaults to request URL domain)No
Do not mix headers and cookies in the same request. Choose one method based on your needs.

​
Usage

​
Send custom headers

Include headers as an object: 
from nimble 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)

​
POST requests with headers

Send POST requests with custom headers and body: 
from nimble 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)

​
Send cookies (string format)

Use simple string format for multiple cookies: 
from nimble 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)

​
Send cookies (object format)

Use object format for domain-specific cookies: 
from nimble 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)

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