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

# LiteLLM

> Nimble is a native search provider in LiteLLM: reach Nimble Search from the LiteLLM Python SDK or the AI Gateway with a single parameter.

### Overview

[LiteLLM](https://github.com/BerriAI/litellm) is an SDK and AI gateway that gives 100+ LLM providers one OpenAI-shaped interface. Its Search API does the same for web search backends.

Nimble ships as the `nimble` search provider, built into LiteLLM itself. Calls go to Nimble's [Search API](/nimble-sdk/web-tools/search) and come back in LiteLLM's unified search response. No fork, no plugin, no custom adapter.

The provider ships in **LiteLLM v1.98.0 and later**. Pin that floor rather than installing "latest":

```bash theme={"system"}
pip install "litellm>=1.98.0"
```

<Note>
  `v1.97.0` shipped without the provider. An existing install that predates `v1.98.0` needs an upgrade before `search_provider="nimble"` resolves.
</Note>

### What this integration covers

This is the Search API only. `search_provider: nimble` routes to `POST /v2/search` and nothing else.

Extract, Map, Crawl, and the Web Search Agent research product are not reachable through LiteLLM today. To use those, call the [Nimble SDK](/nimble-sdk/getting-started/overview) directly or connect the [Nimble MCP server](/integrations/mcp-server/mcp-server).

### Quick Start

#### 1. Get a Nimble API key

Get your API key from [Nimble's dashboard](https://online.nimbleway.com/settings/api-keys) (free trial available) and export it:

```bash theme={"system"}
export NIMBLE_API_KEY="your-api-key"
```

#### 2. Search from the Python SDK

Call `search()` with `search_provider="nimble"`:

```python theme={"system"}
import os
from litellm import search

os.environ["NIMBLE_API_KEY"] = "your-api-key"

response = search(
    query="latest AI developments",
    search_provider="nimble",
    max_results=5,
)

for result in response.results:
    print(f"{result.title}: {result.url}")
    print(result.snippet)
```

`search_provider` is required and has no default. LiteLLM does not pick a search backend for you, so installing the package is not enough to reach Nimble. An async `asearch()` with the same signature is also available.

#### 3. Or search through the AI Gateway

Register Nimble as a search tool in `config.yaml`:

```yaml theme={"system"}
search_tools:
  - search_tool_name: nimble-search
    litellm_params:
      search_provider: nimble
      api_key: os.environ/NIMBLE_API_KEY
```

Start the gateway:

```bash theme={"system"}
litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000
```

Then call the search endpoint. The path segment is the `search_tool_name` you registered:

```bash theme={"system"}
curl http://0.0.0.0:4000/v1/search/nimble-search \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments",
    "max_results": 5
  }'
```

Send your LiteLLM virtual key in the `Authorization` header, not your Nimble key. The gateway holds the Nimble credential server-side, so callers never see it.

### Credentials

<AccordionGroup>
  <Accordion title="NIMBLE_API_KEY" icon="key">
    **Required.** Your Nimble API key. The provider reads it from the environment, or you can pass `api_key=` per call in the SDK and `api_key:` per search tool in the gateway config.

    Without it, the provider raises `NIMBLE_API_KEY is not set` before any request leaves your machine.
  </Accordion>

  <Accordion title="NIMBLE_API_BASE" icon="link">
    **Optional.** Overrides the API base. Defaults to `https://sdk.nimbleway.com/v2`, and the provider appends `/search` itself. Set it only to point at a proxy or a regional endpoint.
  </Accordion>
</AccordionGroup>

### Parameters

LiteLLM maps four unified parameters onto Nimble's names, then forwards every other parameter to the Search API untouched.

<AccordionGroup>
  <Accordion title="Unified parameters LiteLLM maps" icon="arrows-left-right">
    | LiteLLM parameter      | Sent to Nimble as                                                                    |
    | ---------------------- | ------------------------------------------------------------------------------------ |
    | `query`                | `query`. A list is joined with spaces, since Nimble takes one string.                |
    | `max_results`          | `max_results`, unclamped. Nimble validates the 1 to 100 range and reports the error. |
    | `country`              | `country`, upper-cased to the ISO-2 form Nimble expects.                             |
    | `search_domain_filter` | `include_domains`, with `-`-prefixed hosts going to `exclude_domains`.               |
    | `max_tokens_per_page`  | Dropped. Nimble has no equivalent.                                                   |

    Passing Nimble's own `include_domains` or `exclude_domains` overrides anything derived from `search_domain_filter`.
  </Accordion>

  <Accordion title="Nimble parameters passed straight through" icon="forward">
    Anything LiteLLM does not recognize goes into the request body as-is, so Nimble's full parameter surface stays reachable. The values below are what the Search API accepts. LiteLLM does not validate them, so it is not the source of truth for allowed values.

    ```python theme={"system"}
    response = search(
        query="latest tech news",
        search_provider="nimble",
        max_results=5,
        focus="general",
        search_depth="deep",
        time_range="week",
        output_format="markdown",
    )
    ```

    | Parameter                 | Accepted values                                                                                                                                   |
    | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `focus`                   | `general` (default), `news`, `location`, `coding`, `academic`, `geo`, `shopping`, `social`. Also takes a list of explicit Extract Template names. |
    | `search_depth`            | `lite`, `fast`, `deep`. Some focus modes accept only `lite` and `deep`: see [Focus Modes](/nimble-sdk/web-tools/search#focus-modes).              |
    | `time_range`              | `hour`, `day`, `week`, `month`, `year`. Cannot be combined with `start_date` or `end_date`.                                                       |
    | `start_date` / `end_date` | `YYYY-MM-DD` or `YYYY`.                                                                                                                           |
    | `output_format`           | `plain_text`, `markdown` (default), `simplified_html`.                                                                                            |
    | `content_type`            | A **list**, never a string: `["pdf"]`, `["documents", "spreadsheets"]`. Only valid with `focus="general"`.                                        |
    | `locale`                  | Language code such as `en`, `fr`, `de`. Defaults to `en`.                                                                                         |
    | `max_subagents`           | 1 to 10. Applies to the `shopping`, `social`, and `geo` focus modes.                                                                              |

    Full reference: [Search API](/api-reference/search/search).
  </Accordion>
</AccordionGroup>

### Cost tracking on the gateway

`nimble/search` is priced in LiteLLM's own model cost map, so Nimble spend lands in LiteLLM's spend logs and dashboard alongside your model spend. No extra configuration is needed.

LiteLLM's figure is an estimate, not your invoice. It applies one flat per-query rate to every search, which does not model how Nimble bills:

* Nimble prices Search by `search_depth`, and `lite` costs less per search than `fast`. LiteLLM charges the same figure for both.
* `search_depth="deep"` adds a live extraction surcharge on top, billed at Extract rates for each page scraped in real time.
* Volume plans price differently from pay-as-you-go.

See [Pricing](/nimble-sdk/admin/pricing) for the authoritative rates.

### Additional Resources

<CardGroup cols={2}>
  <Card title="Nimble on LiteLLM" icon="book-open" href="https://docs.litellm.ai/docs/search/nimble">
    The provider reference in LiteLLM's own documentation.
  </Card>

  <Card title="Nimble Search API" icon="magnifying-glass" href="/api-reference/search/search">
    Every parameter the provider can forward, with accepted values.
  </Card>

  <Card title="Search" icon="globe" href="/nimble-sdk/web-tools/search">
    Focus modes, search depth, and filtering explained.
  </Card>

  <Card title="Nimble MCP Server" icon="plug" href="/integrations/mcp-server/mcp-server">
    Reach Extract, Map, and Crawl, which LiteLLM does not cover.
  </Card>
</CardGroup>