Skip to main content
Install the Nimble Python library to interact with the Nimble API from your Python applications. Supports both synchronous and asynchronous usage with full type hints.

​
Installation

pip install nimble_python
Requires Python 3.9+. Never hardcode your API key — use environment variables instead.

​
Setup

Initialize the client with your API key. We recommend loading it from the environment:
Python
import os
from nimble_python import Nimble

client = Nimble(api_key=os.environ.get("NIMBLE_API_KEY"))

​
Quick Start

Extract clean content from a URL in one call:
Python
import os
from nimble_python import Nimble

client = Nimble(api_key=os.environ.get("NIMBLE_API_KEY"))

result = client.extract(url="https://www.example.com", render=True)
print(result.task_id)

​
Core Methods

​
Extract

Get clean HTML, markdown, or structured data from any URL. Supports JavaScript rendering, stealth mode, browser actions, and more.
Python
result = client.extract(
    url="https://www.example.com",
    render=True
)

print(result.task_id)
See the Extract docs for the full parameter list — geo-targeting, output formats, parsing schemas, and more.
Perform real-time web searches and get structured results:
Python
result = client.search(
    query="best web scraping tools",
    country="US"
)

print(result)

​
Map

Discover all URLs within a domain or sitemap:
Python
result = client.map(
    URL="https://www.example.com",
    sitemap="only"
)

print(result)

​
Crawl

Recursively crawl and extract an entire website at scale:
Python
result = client.crawl.run(
    url="https://www.example.com",
    limit=100
)

print(result)

​
Agents

Run pre-built agents for structured data from popular platforms:
Python
result = client.agent.run(
    agent="amazon_pdp",
    params={"asin": "B08N5WRWNW"}
)

print(result)
Browse the full agent catalog in the Agent Gallery.

​
Async Client

Use AsyncNimble for non-blocking, concurrent operations:
Python
import asyncio
import os
from nimble_python import AsyncNimble

client = AsyncNimble(api_key=os.environ.get("NIMBLE_API_KEY"))

async def main():
    result = await client.extract(url="https://www.example.com", render=True)
    print(result.task_id)

asyncio.run(main())

​
aiohttp Backend

For high-concurrency workloads, use the aiohttp HTTP backend (requires pip install "nimble_python[aiohttp]"):
Python
import asyncio
import os
from nimble_python import AsyncNimble, DefaultAioHttpClient

async def main():
    async with AsyncNimble(
        api_key=os.environ.get("NIMBLE_API_KEY"),
        http_client=DefaultAioHttpClient(),
    ) as client:
        result = await client.extract(url="https://www.example.com", render=True)
        print(result.task_id)

asyncio.run(main())
Always use async with when working with DefaultAioHttpClient to ensure proper resource cleanup.

​
Error Handling

The SDK maps API failures to typed exception classes:
Python
import nimble_python
import os
from nimble_python import Nimble

client = Nimble(api_key=os.environ.get("NIMBLE_API_KEY"))

try:
    result = client.extract(url="https://www.example.com")
except nimble_python.APIConnectionError as e:
    print("Connection failed:", e)
except nimble_python.AuthenticationError as e:
    print("Invalid API key — check NIMBLE_API_KEY")
except nimble_python.RateLimitError as e:
    print("Rate limited — back off and retry:", e)
except nimble_python.APIStatusError as e:
    print(f"API error {e.status_code}:", e.message)
ExceptionHTTP StatusWhen it occurs
APIConnectionError—Network failure or timeout
AuthenticationError401Invalid or missing API key
PermissionDeniedError403Insufficient account permissions
RateLimitError429Request rate exceeded
InternalServerError500+Server-side error

​
Configuration

​
Timeouts & Retries

The SDK retries automatically on connection errors and server failures. Defaults: 2 retries, 3-minute timeout.
Python
import os
from nimble_python import Nimble

# Configure globally
client = Nimble(
    api_key=os.environ.get("NIMBLE_API_KEY"),
    max_retries=3,
    timeout=60.0,  # seconds
)

# Override per-request
result = client.with_options(max_retries=0).extract(
    url="https://www.example.com"
)

​
Logging

Enable SDK-level debug logging via environment variable: 
export NIMBLE_LOG=debug
Or configure programmatically:
Python
import logging

logging.basicConfig()
logging.getLogger("nimble_python").setLevel(logging.DEBUG)

​
Advanced

​
Raw Response Access

Access HTTP headers and response metadata alongside the parsed result:
Python
response = client.with_raw_response.extract(url="https://www.example.com")
print(response.headers.get("x-request-id"))

result = response.parse()
print(result.task_id)

​
Streaming Response

Stream large response bodies instead of buffering them in memory:
Python
with client.with_streaming_response.extract(url="https://www.example.com") as response:
    for chunk in response.iter_bytes():
        process(chunk)

​
Next Steps

API Reference

Full REST API documentation for all endpoints

Extract

Rendering, formats, stealth mode, and more

Search

Real-time web search with structured results

Agents

Pre-built extraction agents for popular platforms