fetch-use 0.3.0

Python client for Browser-Use Fetch HTTP service

fetch-use

Python client for the Browser-Use Fetch HTTP service. Routes HTTP requests through Browser-Use's proxy infrastructure with Chrome TLS fingerprinting, session-based IP persistence, and server-side cookie management.

Installation

pip install fetch-use

Quick Start

import os
from fetch_use import fetch_sync

os.environ["PROJECT_ID"] = "your-project-id"

response = fetch_sync("https://httpbin.org/get")
print(response.status_code)  # 200
print(response.json())

Or async:

import asyncio
from fetch_use import fetch

async def main():
    response = await fetch("https://httpbin.org/get")
    print(response.json())

asyncio.run(main())

Configuration

Variable	Required	Description
PROJECT_ID	Yes	Your Browser-Use project ID (used for authentication)
SESSION_ID	No	Session ID for IP/cookie persistence. If not set, a random UUID is generated per request (ephemeral, no persistence).
FETCH_USE_URL	No	Override service URL (for testing/self-hosting)

Session Persistence

By default, each request gets a random session ID — meaning a fresh IP, fresh fingerprint, and no cookie persistence between calls.

To maintain the same IP, fingerprint, and cookies across consecutive requests, provide a consistent session ID. You can do this two ways:

Option 1: Environment variable (applies to all requests in the process):

import os
import uuid

os.environ["SESSION_ID"] = str(uuid.uuid4())

# All fetch_sync calls now share the same session automatically
page1 = fetch_sync("https://example.com/page1")
page2 = fetch_sync("https://example.com/page2")  # same IP, cookies carry over

Option 2: Per-request parameter (for fine-grained control):

from fetch_use import fetch_sync

session = "my-scraping-session-1"

page1 = fetch_sync("https://example.com/page1", session_id=session)
page2 = fetch_sync("https://example.com/page2", session_id=session)

This is important when:

• A site sets cookies on the first request that subsequent requests need
• You need a consistent IP to avoid being flagged as a new visitor
• Login flows where cookies from the auth request must carry over

If you don't need persistence (independent one-off requests), you can omit SESSION_ID entirely.

Usage

Basic GET Request

from fetch_use import fetch_sync

response = fetch_sync("https://example.com")
if response.ok:
    print(response.text)

POST with JSON

response = fetch_sync(
    "https://api.example.com/data",
    method="POST",
    json_body={"name": "John", "email": "[e-mail]"},
)
data = response.json()

Custom Headers and Cookies

response = fetch_sync(
    "https://example.com/api",
    headers={
        "Authorization": "Bearer token123",
        "Accept": "application/json",
    },
    cookies={
        "session": "abc123",
    },
)

Proxy Country

# Route through German proxy
response = fetch_sync("https://example.com", proxy_country="DE")

Retry Configuration

from fetch_use import fetch_sync, RetryConfig

response = fetch_sync(
    "https://example.com",
    retry=RetryConfig(
        count=5,
        on_status=[500, 502, 503, 504, 429],
        backoff_ms=200,
    ),
)

Server-Side Cookies

Cookies are persisted server-side per session. Use the cookies parameter to add or override cookies for a specific request:

response = fetch_sync(
    "https://example.com/dashboard",
    cookies={"session": "my-session-cookie"},
)

Cookies set by the server (via Set-Cookie headers) are automatically persisted for subsequent requests within the same session.

Response Object

Property	Type	Description
status_code	int	HTTP status code
status	str	Full status string (e.g., "200 OK")
headers	dict	Response headers
body / text	str	Response body as text
content	bytes	Response body as bytes (handles binary)
ok	bool	True if status is 2xx
final_url	str	Final URL after redirects
redirect_count	int	Number of redirects followed
protocol	str	HTTP protocol (e.g., "HTTP/2.0")

Methods:

• json() — Parse body as JSON
• raise_for_status() — Raise FetchError if status >= 400

Error Handling

from fetch_use import fetch_sync, FetchError

try:
    response = fetch_sync("https://example.com")
    response.raise_for_status()
    data = response.json()
except FetchError as e:
    print(f"Error: {e}")
    print(f"Code: {e.code}")
    print(f"Details: {e.details}")

License

MIT