Python - Nimble Docs

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

pip install "nimble_python[aiohttp]"

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.

Search

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)

Exception	HTTP Status	When it occurs
`APIConnectionError`	—	Network failure or timeout
`AuthenticationError`	401	Invalid or missing API key
`PermissionDeniedError`	403	Insufficient account permissions
`RateLimitError`	429	Request rate exceeded
`InternalServerError`	500+	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

​Installation

​Setup

​Quick Start

​Core Methods

​Extract

​Search

​Map

​Crawl

​Agents

​Async Client

​aiohttp Backend

​Error Handling

​Configuration

​Timeouts & Retries

​Logging

​Advanced

​Raw Response Access

​Streaming Response

​Next Steps

API Reference

Extract

Search

Agents

Installation

Setup

Quick Start

Core Methods

Extract

Search

Map

Crawl

Agents

Async Client

aiohttp Backend

Error Handling

Configuration

Timeouts & Retries

Logging

Advanced

Raw Response Access

Streaming Response

Next Steps