Search

Nimble Search reads the live web in real time and returns structured, agent-ready results. Every answer reflects what’s on the page right now, not a snapshot from earlier. Pick how much content comes back with search_depth, from titles and snippets up to full page markdown.

Perform a Search with Nimble

Get an API key from the Nimble Platform and install a client:

pip install nimble_python

npm install @nimble-way/nimble-js

go get github.com/Nimbleway/nimble-go@latest

npm install -g @nimble-way/nimble-cli
export NIMBLE_API_KEY="YOUR-API-KEY"

Make a search call

from nimble_python import Nimble

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

result = nimble.search(
    query="latest developments in AI agents 2026",
    max_results=5
)

print(f"Found {len(result.results)} results")
for item in result.results:
    print(f"- {item.title}: {item.url}")

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.search({
  query: "latest developments in AI agents 2026",
  max_results: 5,
});

console.log(`Found ${result.results.length} results`);
result.results.forEach(item => {
  console.log(`- ${item.title}: ${item.url}`);
});

package main

import (
    "context"
    "fmt"

    nimble "github.com/Nimbleway/nimble-go"
    "github.com/Nimbleway/nimble-go/option"
    "github.com/Nimbleway/nimble-go/packages/param"
)

func main() {
    client := nimble.NewClient(option.WithAPIKey("YOUR-API-KEY"))

    result, err := client.Search(context.Background(), nimble.SearchParams{
        Query:      "latest developments in AI agents 2026",
        MaxResults: param.NewOpt(int64(5)),
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Found %d results\n", len(result.Results))
    for _, item := range result.Results {
        fmt.Printf("- %s: %s\n", item.Title, item.URL)
    }
}

nimble search \
  --query "latest developments in AI agents 2026" \
  --max-results 5

curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "latest developments in AI agents 2026",
    "max_results": 5
}'

Read the response

No search_depth was set, so this used the default, fast. Each result carries a title, URL, description, and metadata:

{
  "total_results": 5,
  "results": [
    {
      "title": "AI Agents: The Next Frontier in 2026",
      "description": "Exploring the latest breakthroughs in autonomous AI agents...",
      "url": "https://example.com/ai-agents-2026",
      "metadata": {
        "position": 1,
        "entity_type": "OrganicResult",
        "country": "US",
        "locale": "en"
      }
    },
    {...}
  ],
  "request_id": "84f08ac1-bb5f-4b6f-8447-2d21cb930416"
}

Search Depth

The search_depth parameter controls how much content each search returns. Choose the right depth for your use case.

Depth	Content Returned	Best For
`lite`	Titles, URLs, snippets	Quick factual questions, high-volume monitoring, filtering
`fast` (default)	Rich content	RAG, chatbots, real-time AI agent workflows
`deep`	Full real-time page extraction	Research, due diligence, comprehensive analysis

Search Depth Best Practices

Learn when to use each depth mode, optimization tips, and cost strategies.

Parameters

API Parameters

For detailed parameter documentation, see the Search API Reference.

Key Features

Time-based filtering

Filter results by recency using time_range or specify exact date ranges. Essential for news monitoring, tracking recent developments, or analyzing historical data within specific timeframes.

from nimble_python import Nimble

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

# Filter by time range
result = nimble.search(
    query="AI news",
    max_results=20,
    time_range="week"
)

# Or use specific date range
result = nimble.search(
    query="machine learning advances",
    max_results=15,
    start_date="2026-01-01",
    end_date="2026-01-31"
)

print(result)

import Nimble from '@nimble-way/nimble-js';

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

// Filter by time range
const result1 = await nimble.search({
  query: "AI news",
  max_results: 20,
  time_range: "week"
});

// Or use specific date range
const result2 = await nimble.search({
  query: "machine learning advances",
  max_results: 15,
  start_date: "2026-01-01",
  end_date: "2026-01-31"
});

console.log(result1);

# Filter by time range
curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "AI news",
    "max_results": 20,
    "time_range": "week"
}'

# Or use specific date range
curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "machine learning advances",
    "max_results": 15,
    "start_date": "2026-01-01",
    "end_date": "2026-01-31"
}'

Domain filtering

Filter results to specific domains or exclude unwanted ones. Focus on trusted sources, exclude noise (social media, ads), or search within curated lists of authoritative sites.

from nimble_python import Nimble

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

# Only search within specific domains
result = nimble.search(
    query="python async patterns",
    max_results=10,
    include_domains=["github.com", "stackoverflow.com", "docs.python.org"]
)

# Or exclude specific domains
result = nimble.search(
    query="web scraping tutorial",
    max_results=10,
    exclude_domains=["pinterest.com", "youtube.com"]
)

print(result)

import Nimble from '@nimble-way/nimble-js';

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

// Only search within specific domains
const result1 = await nimble.search({
  query: "python async patterns",
  max_results: 10,
  include_domains: ["github.com", "stackoverflow.com", "docs.python.org"]
});

// Or exclude specific domains
const result2 = await nimble.search({
  query: "web scraping tutorial",
  max_results: 10,
  exclude_domains: ["pinterest.com", "youtube.com"]
});

console.log(result1);

# Only search within specific domains
curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "python async patterns",
    "max_results": 10,
    "include_domains": ["github.com", "stackoverflow.com", "docs.python.org"]
}'

# Or exclude specific domains
curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "web scraping tutorial",
    "max_results": 10,
    "exclude_domains": ["pinterest.com", "youtube.com"]
}'

Document type filtering

Search for specific document types like PDFs, spreadsheets, or presentations (only works with focus: "general"). Perfect for academic research, finding reports, whitepapers, or structured data files.

from nimble_python import Nimble

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

# Search for PDF documents
result = nimble.search(
    query="machine learning research papers",
    max_results=10,
    focus="general",
    content_type=["pdf"]
)

# Search for multiple document types
result = nimble.search(
    query="financial reports 2026",
    max_results=15,
    focus="general",
    content_type=["pdf", "xlsx", "docx"]
)

# Use semantic groups for broader filtering
result = nimble.search(
    query="quarterly earnings",
    max_results=10,
    focus="general",
    content_type=["documents", "spreadsheets"]
)

print(result)

import Nimble from '@nimble-way/nimble-js';

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

// Search for PDF documents
const result1 = await nimble.search({
  query: "machine learning research papers",
  max_results: 10,
  focus: "general",
  content_type: ["pdf"]
});

// Search for multiple document types
const result2 = await nimble.search({
  query: "financial reports 2026",
  max_results: 15,
  focus: "general",
  content_type: ["pdf", "xlsx", "docx"]
});

// Use semantic groups for broader filtering
const result3 = await nimble.search({
  query: "quarterly earnings",
  max_results: 10,
  focus: "general",
  content_type: ["documents", "spreadsheets"]
});

console.log(result1);

# Search for PDF documents
curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "machine learning research papers",
    "max_results": 10,
    "focus": "general",
    "content_type": ["pdf"]
}'

# Use semantic groups for broader filtering
curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "quarterly earnings",
    "max_results": 10,
    "focus": "general",
    "content_type": ["documents", "spreadsheets"]
}'

content_type only works with focus: "general". Supported formats: pdf, docx, xlsx, pptx, and semantic groups: documents, spreadsheets, presentations.

Focus Modes

Focus modes route your searches to specialized sources optimized for different use cases, powered by Extract Templates that retrieve the most relevant results.

Available Pre-defined Modes

Pre-defined focus modes automatically route your search to specialized Extract Templates based on your query type. Simply specify the mode that matches your use case.

Focus Mode	Best For
`general` (default)	General information, broad topics, web pages
`news`	Current events, breaking stories, journalism
`coding`	Code examples, debugging, API documentation
`academic`	Scientific research, peer-reviewed studies
`shopping`	Product comparison, pricing, merchant reviews
`social`	Social content, influencers, trending topics
`geo`	AI-generated answers, synthetic insights
`location`	Places, businesses, geographic information

news, location, coding, and academic only support search_depth: "lite" or "deep".

Example: Shopping search

Compare products across e-commerce platforms:

from nimble_python import Nimble

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

result = nimble.search(
    query="wireless noise canceling headphones",
    focus="shopping",
    max_results=20,
    max_subagents=5  # Search more platforms in parallel
)

print(result)

import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({ apiKey: "YOUR-API-KEY" });

const result = await nimble.search({
  query: "wireless noise canceling headphones",
  focus: "shopping",
  max_results: 20,
  max_subagents: 5,
});

console.log(result);

curl -X POST 'https://sdk.nimbleway.com/v2/search' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": "wireless noise canceling headphones",
    "focus": "shopping",
    "max_results": 20,
    "max_subagents": 5
}'

Custom Focus Mode

For advanced use cases, you can explicitly specify which search agents to use by passing an array of subagent names to the focus parameter. This gives you full control over data sources and enables mixing agents from different focus modes. Example:

{
  "query": "best wireless headphones",
  "focus": ["amazon_serp", "walmart_serp", "reddit_discover_posts"],
  "max_results": 10
}

Available Extract Templates

View the complete list of Extract Templates you can use in custom focus modes.

Search vs other tools

Need	Use
Search web + extract content from results	Search
Data from popular sites	Templates - maintained by Nimble
Data from specific URLs	Extract
URLs with context for AI planning	Map
Data from entire website	Crawl

Use cases

Research & Data Collection

Gather comprehensive information on any topic from multiple sources automatically

AI Agent Tasks

Get quick, structured web results for your applications

Content Monitoring

Track mentions, news, or updates about specific topics, brands, or keywords

Competitive Intelligence

Monitor what’s being said about competitors or track industry trends

Next steps

API Reference

Explore endpoints, request parameters, and response schemas

Web Tools Skill

Add real-time web intelligence tools to Claude Code and other AI agents

LangChain Integration

Connect Nimble Search to your LangChain applications

Getting Started

Search Tools

Web Search Agent

Extraction Tools

Extract Template

Extract Jobs

Guides

SDKs

Admin

Proxy

Perform a Search with Nimble

Search Depth

Search Depth Best Practices

Parameters

API Parameters

Key Features

Focus Modes

Available Pre-defined Modes

Example: Shopping search

Custom Focus Mode

Available Extract Templates

Search vs other tools

Use cases

Research & Data Collection

AI Agent Tasks

Content Monitoring

Competitive Intelligence

Next steps

API Reference

Web Tools Skill

LangChain Integration

​Perform a Search with Nimble

​Search Depth

Search Depth Best Practices

​Parameters

API Parameters

​Key Features

​Focus Modes

​Available Pre-defined Modes

​Example: Shopping search

​Custom Focus Mode

Available Extract Templates

​Search vs other tools

​Use cases

Research & Data Collection

AI Agent Tasks

Content Monitoring

Competitive Intelligence

​Next steps

API Reference

Web Tools Skill

LangChain Integration

Perform a Search with Nimble

Search Depth

Parameters

Key Features

Focus Modes

Available Pre-defined Modes

Example: Shopping search

Custom Focus Mode

Search vs other tools

Use cases

Next steps