Skip to main content
Nimble Web **Search Agents (WSA) **are pre-built, production-ready extractors for popular platforms like Amazon, LinkedIn, Google, and more. Use simple params like product IDs or search terms instead of complex configurations.

​
When to use

Use the agent API when you need to:
  • Quick extraction: Get data without configuring selectors
  • Production-ready: Use battle-tested extractors maintained by Nimble
  • Simple params: Provide IDs or terms instead of constructing URLs
  • Normalized data: Receive consistent schemas across requests
  • Zero maintenance: Let Nimble handle site changes

​
API endpoint

POST https://sdk.nimbleway.com/v1/agent

​
Parameters

​
agent
string
required
The name of the pre-built agent you want to use. Each agent is designed for a specific platform or data type.Popular agents:
  • amazon_pdp - Amazon product pages
  • amazon_serp - Amazon search results
  • google_search - Google search results
  • google_maps_search - Google Maps locations
  • walmart_pdp - Walmart products
  • chatgpt - ChatGPT prompt results
  • perplexity - Perplexity prompt results
  • gemini - Google Gemini prompt results
Example:
"agent": "amazon_pdp"
​
params
object
required
Agent-specific parameters that tell the agent what data to fetch. Each agent has different requirements.Common param types:
  • Product IDs (ASINs, SKUs)
  • Search queries
  • URLs or usernames
  • Location information
  • Page numbers
The exact params depend on which agent you’re using.
Example:
"params": {
  "asin": "B08N5WRWNW",
  "country": "US",
  "zipcode": "90210"
}
​
localization
boolean
Controls if localization sould be enabled (default false).Some agent support localization based on zip_code or store_id on the site it self. Relevant only when agent is supporting localizationCommon related param types:
  • Zip code - selecting localization based on ZIP code user input
  • Store ID - selecting localization based on Store ID user input
For agents supporting localization, you must enable localization and pass the localization input under params.
Use the Agent’s Gallery to understand each agent’s capabilities, including localization support.
Example:
"localization":true,
"params": {
  "asin": "B08N5WRWNW",
  "country": "US",
  "zipcode": "90210"
}
Each agent has unique parameter requirements. The params you provide depend entirely on which agent you’re using. Check the agent-specific documentation for exact requirements.

​
Usage

​
Product search results extraction

Extract search on product listings from e-commerce platforms: 
from nimble_python import Nimble

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

# Amazon search
result = nimble.agent(
    agent="amazon_serp",
    params={
        "query": "wireless headphones",
        "country": "US"
    }
)

print(f"Found {len(result['data']['parsing'])} products")
for product in result['data']['parsing']:
    print(f"- {product['product_name']}: ${product['price']}")

​
E-commerce extraction

Extract product data from popular platforms: 
from nimble_python import Nimble

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

# Amazon product
amazon_result = nimble.agent(
    agent="amazon_pdp",
    params={
        "asin": "B08N5WRWNW",
        "country": "US"
    }
)

print(f"Product: {amazon_result['data']['parsing']['product_title']}")
print(f"Price: ${amazon_result['data']['parsing']['web_price']}")

# Walmart product
walmart_result = nimble.agent(
    agent="walmart_pdp",
    params={
        "product_id": "123456789"
    }
)

print(f"Product: {walmart_result['data']['parsing']['product_title']}")
print(f"Price: {walmart_result['data']['parsing']['price']}")

​
Search engine extraction

Get search results from Google and Bing: 
from nimble_python import Nimble

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

# Google search
google_result = nimble.agent(
    agent="google_search",
    params={
        "query": "best laptop 2026"
    }
)

print("Google results:")
for result in google_result['data']['parsing']['entities']['OrganicResult']:
    print(f"- {result['title']}")
    print(f"  {result['url']}")

# Google Maps
maps_result = nimble.agent(
    agent="google_maps_search",
    params={
        "query": "coffee shops"
    }
)

print(f"\nFound {len(maps_result['data']['parsing']['entities']['SearchResult'])} locations")
for place in maps_result['data']['parsing']['entities']['SearchResult']:
    print(f"- {place['title']} ({place['rating']})")

​
Async agent extraction

Run agent extractions asynchronously for batch processing and long-running operations. Async-specific parameters: In addition to the standard agent and params parameters, async requests support optional parameters:
  • callback_url (string): Webhook URL to receive a POST notification when the task completes
  • storage_type (string): Storage provider for results (s3 for Amazon S3 or gs for Google Cloud Storage)
  • storage_url (string): Repository URL where results will be saved (e.g., s3://my-bucket/nimble-results/)
  • storage_compress (boolean): Compress results using GZIP before saving to storage
  • storage_object_name (string): Custom name for the stored object instead of the default task ID
For complete async documentation and all parameters, see Async Requests. Basic usage: 
from nimble_python import Nimble
import time

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

# Submit async agent extraction
response = nimble.agent_async(
    agent="amazon_pdp",
    params={
        "asin": "B08N5WRWNW",
        "country": "US"
    }
)

task_id = response['task']['id']
print(f"Task created: {task_id}")

# Poll for completion
while True:
    status = nimble.get_task_status(task_id)
    print(f"Status: {status['state']}")

    if status['state'] == 'completed':
        results = nimble.get_task_results(task_id)
        print(f"Product: {results['data']['parsing']['title']}")
        print(f"Price: ${results['data']['parsing']['price']['current']}")
        break
    elif status['state'] == 'failed':
        print(f"Task failed: {status.get('error')}")
        break

    time.sleep(5)

# Batch processing multiple products
products = ["B08N5WRWNW", "B0BDJ3L3XJ", "B0CHXQ3XZ1"]
task_ids = []

for asin in products:
    response = nimble.agent_async(
        agent="amazon_pdp",
        params={"asin": asin}
    )
    task_ids.append(response['task']['id'])
    print(f"Submitted: {asin} → {response['task']['id']}")

# Wait for all tasks to complete
completed = []
while len(completed) < len(task_ids):
    for task_id in task_ids:
        if task_id in completed:
            continue

        status = nimble.get_task_status(task_id)
        if status['state'] in ['completed', 'failed']:
            completed.append(task_id)
            print(f"Finished: {task_id} ({status['state']})")

    if len(completed) < len(task_ids):
        time.sleep(5)

# Retrieve all results
for task_id in task_ids:
    results = nimble.get_task_results(task_id)
    if results.get('data'):
        print(f"\n{results['data']['parsing']['title']}: ${results['data']['parsing']['price']['current']}")
With webhook and cloud storage: 
from nimble_python import Nimble

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

# With webhook notification
response = nimble.agent_async(
    agent="amazon_pdp",
    params={
        "asin": "B08N5WRWNW",
        "country": "US"
    },
    callback_url="https://your-api.com/webhooks/agent-complete"
)

print(f"Task created: {response['task']['id']}")
print("Webhook will be called when extraction completes")

# With cloud storage (S3)
response = nimble.agent_async(
    agent="walmart_pdp",
    params={
        "product_id": "123456789"
    },
    storage_type="s3",
    storage_url="s3://my-bucket/nimble-extracts/",
    storage_compress=True,
    storage_object_name="walmart-product-123456789"
)

print(f"Task created: {response['task']['id']}")
print(f"Results will be saved to: s3://my-bucket/nimble-extracts/walmart-product-123456789.json.gz")
For complete async documentation including all parameters, webhook payload format, cloud storage configuration, and best practices, see Async Requests.

​
Example response

When an agent executes successfully, you receive normalized data: 
{
    "url": "https://www.officedepot.com/a/products/296070/",
    "task_id": "b1fa7943-cba5-4ec2-a88c-4d2d6799c794",
    "status": "success",
	"data": {
		"html": "...",
		"parsing": {
            "type": "parsed",
            "parsed": {
                "product_url": "https://www.officedepot.com/a/products/296070/Pilot-G-2-Retractable-Gel-Pens/",
                "sku": "296070",
                "name": "Pilot G2 Retractable Gel Pens, Bold Point, 1.0 mm, Clear Barrels, Black Ink, Pack Of 4",
                "description": "Pilot G-2 retractable gel pens are filled with long-lasting gel ink that is smooth and smearproof. Enjoy the comfort and control that is provided through the ridged rubber grip featured on each Pilot gel pen.",
                "brand": "Pilot",
                "price": "7.99",
                "currency": "USD",
                "seller": "Office Depot",
                "availability": "InStock",
                "condition": "NewCondition",
                "mpn": "31254",
                "moq": 0,
                "uom": "Pack",
                "pack_size": "4",
                "rating": "4.9",
                "review_count": "715",
                "image": "https://media.officedepot.com/images/f_auto,q_auto,e_sharpen,h_450/products/296070/296070_p_pilot_g_2_retractable_gel_pens/296070",
                "specification": [
                    {
                        "specification_key": "Item #",
                        "specification_value": "296070"
                    },
                    {
                        "specification_key": "Manufacturer #",
                        "specification_value": "31254"
                    },
                    {
                        "specification_key": "Total Quantity",
                        "specification_value": "4 Pens"
                    },
                    {
                        "specification_key": "Color (Ink)",
                        "specification_value": "Black"
                    },
                    {
                        "specification_key": "point size",
                        "specification_value": "1.0 mm"
                    },
                    {
                        "specification_key": "Color (Barrel)",
                        "specification_value": "Clear"
                    },
                    {
                        "specification_key": "point type",
                        "specification_value": "Bold"
                    },
                    {
                        "specification_key": "Number of Packs/Boxes",
                        "specification_value": "1"
                    },
                    {
                        "specification_key": "quantity",
                        "specification_value": "4"
                    },
                    {
                        "specification_key": "click style",
                        "specification_value": "Top"
                    },
                    {
                        "specification_key": "erasable",
                        "specification_value": "No"
                    },
                    {
                        "specification_key": "grip type",
                        "specification_value": "Rubberized"
                    },
                    {
                        "specification_key": "ink type",
                        "specification_value": "Gel"
                    },
                    {
                        "specification_key": "refillable",
                        "specification_value": "Yes"
                    },
                    {
                        "specification_key": "retractable",
                        "specification_value": "Yes"
                    },
                    {
                        "specification_key": "Smudge Resistant",
                        "specification_value": "No"
                    },
                    {
                        "specification_key": "Material (barrel)",
                        "specification_value": "Resin"
                    },
                    {
                        "specification_key": "pocket clip",
                        "specification_value": "Yes"
                    },
                    {
                        "specification_key": "visible ink supply",
                        "specification_value": "Yes"
                    },
                    {
                        "specification_key": "Product Line",
                        "specification_value": "G2"
                    },
                    {
                        "specification_key": "Quick Drying",
                        "specification_value": "Yes"
                    },
                    {
                        "specification_key": "brand name",
                        "specification_value": "Pilot"
                    },
                    {
                        "specification_key": "Eco-conscious",
                        "specification_value": "Refillable"
                    },
                    {
                        "specification_key": "manufacturer",
                        "specification_value": "PILOT CORPORATION OF AMERICA"
                    },
                    {
                        "specification_key": "UPC",
                        "specification_value": "072838313744"
                    }
                ]
            }
        }
		"headers": {...}
	},
    "metadata": {
        "query_time": "2026-02-08T22:00:36.132Z",
        "query_duration": 1877,
        "response_parameters": {
            "input_url": "https://www.officedepot.com/a/products/296070/"
        },
        "driver": "vx6"
    },
    "status_code": 200
}