nimble-search-reference

name	nimble-search-reference
description	Reference for nimble search command. Load when searching the live web. Contains: all flags, 8 focus modes (general/coding/news/academic/shopping/social/geo/location), search_depth modes (lite/fast/deep), response structure, credit costs.

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