nimbleway/nimble-search-reference

nimble search — reference

Real-time web search with 8 focus modes. Returns results with titles, URLs, and optionally full content and AI answers.

Table of Contents

• Parameters
• Search depth modes
• Focus modes
• CLI
• Python SDK
• Response structure

Parameters

| Parameter | Type | Default | Description | | ------------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | query | string | required | Search query | | search_depth | string | deep | Content depth: lite | fast | deep — see depth table below | | focus | string or array | general| Focus mode (see table below) or array of specific agent names e.g. ["amazon_serp", "target_serp"] | | include_answer | bool | false | AI-synthesized answer (premium — retry without if 402/403) | | max_results | int | 10 | Result count (1–100) | | output_format | string | — | plain_text | markdown | simplified_html | | include_domains | array | — | Restrict to these domains (max 50) | | exclude_domains | array | — | Exclude these domains (max 50) | | time_range | string | — | hour | day | week | month | year — cannot combine with dates | | start_date / end_date | string | — | Date range YYYY-MM-DD — cannot combine with time_range | | content_type | string | — | File type filter: pdf, docx, xlsx, documents, spreadsheets, presentations — only with general focus | | max_subagents | int | — | Parallel agents for shopping/social/geo/location (1–5) | | country | string | — | ISO Alpha-2 geo-targeted results (e.g. US) | | locale | string | — | Language code (e.g. en, fr, de) | | deep_search | bool | — | Deprecated — use search_depth instead. true = deep, false = lite. Still works for backward compat. |

CLI uses hyphens (--search-depth, --include-answer). SDK uses underscores (search_depth, include_answer).

Search depth modes

| Mode | Content | Speed | Best for | | ------ | -------------------------------- | -------- | --------------------------------------------------------------- | | lite | Metadata only (title, URL, snippet) | Fastest | High-volume pipelines, URL discovery, quick filtering | | fast | Rich cached content | Fast | AI agents, RAG, chatbots — quality content without scrape latency | | deep | Full real-time page content | Slowest | Research, due diligence, tasks requiring complete source material |

Default for AI agent use: prefer fast — richest content-to-latency ratio.

Focus modes

| Mode | Best for | Example query | | ---------- | ----------------------------------- | ---------------------------------------- | | general | Broad web (default) | "best practices for X" | | coding | Docs, code, Stack Overflow, GitHub | "how to implement X in Python" | | news | Current events, breaking news | "EU AI Act enforcement 2026" | | academic | Research papers, scholarly articles | "transformer attention mechanisms paper" | | shopping | Products, price comparisons | "best wireless headphones under $200" | | social | People, LinkedIn, X, YouTube | "Jane Doe Head of Engineering" | | geo | Geographic and regional data | "tech companies in Berlin" | | location | Local businesses, restaurants | "italian restaurants San Francisco" |

CLI

# Fast depth — rich content, low latency (best for agents)
nimble search --query "React server components" --search-depth fast

# Lite — metadata only, fastest
nimble search --query "OpenAI announcements" --focus news --search-depth lite

# Deep — full real-time page scrape
nimble search --query "EU AI Act" --focus news --search-depth deep \
  --start-date 2025-01-01 --end-date 2025-12-31

# With AI answer + domain filter
nimble search --query "Python asyncio best practices" \
  --focus coding --search-depth fast --include-answer \
  --include-domain '["docs.python.org", "realpython.com"]'

# Extract just URLs
nimble --transform "results.#.url" search --query "React tutorials" --search-depth lite

Python SDK

from nimble_python import Nimble
nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

# Fast depth — best default for AI agent use
resp = nimble.search(query="React server components", search_depth="fast")

# Lite — scan many results quickly
resp = nimble.search(
    query="OpenAI announcements",
    focus="news",
    search_depth="lite",
    time_range="week",
)

# Deep — full content for research
resp = nimble.search(
    query="EU AI Act enforcement",
    focus="news",
    search_depth="deep",
    include_answer=True,
)

# Custom focus — explicit agent array
resp = nimble.search(
    query="best wireless headphones",
    focus=["amazon_serp", "walmart_serp"],
    search_depth="fast",
    max_results=10,
)

results = resp.results       # list of result objects
answer = resp.answer         # AI summary (if include_answer=True)

Response structure

| Field | Type | Description | | -------------------------------- | ------ | ------------------------------------------------------------ | | total_results | int | Total results returned | | results | array | Search results | | results[].title | string | Page title | | results[].description | string | Snippet | | results[].url | string | Page URL | | results[].content | string | Page content — cached (fast) or real-time scraped (deep) | | results[].metadata.position | int | Result rank | | results[].metadata.entity_type | string | e.g. OrganicResult | | answer | string | AI summary (if include_answer=True) | | request_id | UUID | Request identifier |