> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Real-time web search that understands query intent and returns structured, agent-ready data

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`.

## Perform a Search with Nimble

Get an API key from the [Nimble Platform](https://online.nimbleway.com) and install a client:

<CodeGroup>
  ```bash Python theme={"system"}
  pip install nimble_python
  ```

  ```bash TypeScript theme={"system"}
  npm install @nimble-way/nimble-js
  ```

  ```bash Go theme={"system"}
  go get github.com/Nimbleway/nimble-go@latest
  ```

  ```bash CLI theme={"system"}
  npm install -g @nimble-way/nimble-cli
  export NIMBLE_API_KEY="YOUR-API-KEY"
  ```
</CodeGroup>

<Steps>
  <Step title="Make a search call">
    <CodeGroup>
      ```python Python theme={"system"}
      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}")
      ```

      ```typescript TypeScript theme={"system"}
      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}`);
      });
      ```

      ```go Go theme={"system"}
      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)
          }
      }
      ```

      ```bash CLI theme={"system"}
      nimble search \
        --query "latest developments in AI agents 2026" \
        --max-results 5
      ```

      ```bash cURL theme={"system"}
      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
      }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the response">
    No `search_depth` was set, so this used the default, `standard`. Each result carries a title, URL, description, and metadata:

    ```json theme={"system"}
    {
      "total_results": 5,
      "results": [
        {
          "title": "AI agent trends 2026 report | Google Cloud",
          "description": "Our new report reveals the 5 top trends in agentic AI that can help transform businesses, for 2026 and beyond...",
          "url": "https://cloud.google.com/resources/content/ai-agent-trends-2026",
          "content": "",
          "metadata": {
            "position": 1,
            "entity_type": "SearchResult",
            "country": "US",
            "locale": "en"
          }
        },
        {...}
      ],
      "request_id": "84f08ac1-bb5f-4b6f-8447-2d21cb930416"
    }
    ```
  </Step>
</Steps>

## 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 |
| `standard` (default) | Rich content | RAG, chatbots, real-time AI agent workflows |

Need the full page? Set `full_content: true` alongside either depth. It adds each result's full scraped page content on top of its title, URL, and description, at higher cost.

<Card title="Search Depth Best Practices" icon="lightbulb" href="/nimble-sdk/web-tools/search-depth">
  Learn when to use each depth mode, optimization tips, and cost strategies.
</Card>

## Parameters

<Card title="API Parameters" icon="brackets-curly" href="/api-reference/search/search">
  For detailed parameter documentation, see the Search API Reference.
</Card>

## Key Features

<AccordionGroup>
  <Accordion title="Full page content" icon="scroll">
    Add `full_content: true` to return each result's complete scraped page content. Works with either `search_depth` value, at a higher cost.

    <CodeGroup>
      ```python Python theme={"system"}
      from nimble_python import Nimble

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

      result = nimble.search(
          query="GDPR compliance requirements for SaaS",
          max_results=5,
          full_content=True
      )

      print(result)
      ```

      ```typescript TypeScript theme={"system"}
      import Nimble from '@nimble-way/nimble-js';

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

      const result = await nimble.search({
        query: "GDPR compliance requirements for SaaS",
        max_results: 5,
        full_content: true
      });

      console.log(result);
      ```

      ```bash cURL theme={"system"}
      curl -X POST 'https://sdk.nimbleway.com/v2/search' \
      --header 'Authorization: Bearer <YOUR-API-KEY>' \
      --header 'Content-Type: application/json' \
      --data-raw '{
          "query": "GDPR compliance requirements for SaaS",
          "max_results": 5,
          "full_content": true
      }'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Time-based filtering" icon="clock">
    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.

    <CodeGroup>
      ```python Python theme={"system"}
      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)
      ```

      ```typescript TypeScript theme={"system"}
      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);
      ```

      ```bash cURL theme={"system"}
      # 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"
      }'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Domain filtering" icon="globe">
    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.

    <CodeGroup>
      ```python Python theme={"system"}
      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)
      ```

      ```typescript TypeScript theme={"system"}
      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);
      ```

      ```bash cURL theme={"system"}
      # 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"]
      }'
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Document type filtering" icon="file-lines">
    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.

    <CodeGroup>
      ```python Python theme={"system"}
      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)
      ```

      ```typescript TypeScript theme={"system"}
      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);
      ```

      ```bash cURL theme={"system"}
      # 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"]
      }'
      ```
    </CodeGroup>

    <Note>
      `content_type` only works with `focus: "general"`. Supported formats: `pdf`, `docx`, `xlsx`, `pptx`, and semantic groups: `documents`, `spreadsheets`, `presentations`.
    </Note>
  </Accordion>
</AccordionGroup>

## 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 |

<Note>
  Focus modes only work with `search_depth: "lite"`.
</Note>

### Example: Shopping search

Compare products across e-commerce platforms:

<CodeGroup>
  ```python Python theme={"system"}
  from nimble_python import Nimble

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

  result = nimble.search(
      query="wireless noise canceling headphones",
      focus="shopping",
      search_depth="lite",
      max_results=20
  )

  print(result)
  ```

  ```typescript TypeScript theme={"system"}
  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",
    search_depth: "lite",
    max_results: 20,
  });

  console.log(result);
  ```

  ```bash cURL theme={"system"}
  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",
      "search_depth": "lite",
      "max_results": 20
  }'
  ```
</CodeGroup>

### 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:**

```json theme={"system"}
{
  "query": "best wireless headphones",
  "focus": ["amazon_serp", "walmart_serp", "reddit_discover_posts"],
  "search_depth": "lite",
  "max_results": 10
}
```

<Card title="Available Extract Templates" icon="wand-magic-sparkles" href="/nimble-sdk/agentic/agent-gallery">
  View the complete list of Extract Templates you can use in custom focus modes.
</Card>

## Search vs other tools

| Need | Use |
| - | - |
| Search web + extract content from results | **Search** |
| Data from popular sites | [**Templates**](/nimble-sdk/web-tools/extract/template) - maintained by Nimble |
| Data from specific URLs | **Extract** |
| URLs with context for AI planning | **Map** |
| Data from entire website | **Crawl** |

## Use cases

<CardGroup cols={2}>
  <Card title="Research & Data Collection" icon="magnifying-glass">
    Gather comprehensive information on any topic from multiple sources
    automatically
  </Card>

  <Card title="AI Agent Tasks" icon="robot">
    Get quick, structured web results for your applications
  </Card>

  <Card title="Content Monitoring" icon="newspaper">
    Track mentions, news, or updates about specific topics, brands, or keywords
  </Card>

  <Card title="Competitive Intelligence" icon="chart-line">
    Monitor what's being said about competitors or track industry trends
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card icon="code" href="/api-reference/search/search" title="API Reference">
    Explore endpoints, request parameters, and response schemas
  </Card>

  <Card title="Web Tools Skill" icon="rectangle-terminal" href="/integrations/agent-skills/web-tools-skills/nimble-web-expert">
    Add real-time web intelligence tools to Claude Code and other AI agents
  </Card>

  <Card title="LangChain Integration" icon="link" href="/integrations/connectors/langchain">
    Connect Nimble Search to your LangChain applications
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.