# AI-Search

## Overview

The [**AI-Search**](https://aistudio.oxylabs.io/apps/search) app by [**Oxylabs AI Studio**](https://aistudio.oxylabs.io/) is a web search tool that allows developers to retrieve search results, optionally scrape them, and handle JavaScript-rendered content with ease. It is built to act as an intelligent search agent that simplifies the process of extracting relevant information directly into your Python applications.

Whether you need a simple list of URLs or deep content extraction, AI Search removes the complexity of building custom search scrapers from scratch.

## Key features

* **Query web using plain English:** Simply provide your search query in natural language and let the agent do the heavy lifting.
* **Control number of search results:** Easily define exactly how many results you want to retrieve.
* **Optional content scraping for result pages:** Automatically scrape and extract content snippets directly from the returned search results.
* **Python rendering for dynamic content:** Enable rendering to seamlessly handle and extract data from JavaScript-heavy websites.

## How it works

To use the search agent, follow these simple steps:

1. **Input the search query** you want to look up.
2. **Set the desired number of results** to limit or expand your search scope.
3. **Toggle content scraping and JS rendering** based on whether you need deep content extraction or just URLs and titles.

### Installation

To begin, be sure you have access to an API key (or [get a free trial](https://aistudio.oxylabs.io/register) with **1,000 credits**) and `Python 3.10+` installed. You can install the `oxylabs-ai-studio` package using pip:

```bash
pip install oxylabs-ai-studio
```

### Code example (Python)

The following example demonstrates how to use the `AI-Seaerch` agent for data retrieval scenarios.

```python
from oxylabs_ai_studio.apps.ai_search import AiSearch

search = AiSearch(api_key="<API_KEY>")

query = "lasagna recipes"
result = search.search(
    query=query,
    limit=5,
    render_javascript=False,
    return_content=True,
)
print(result.data)

# Or for fast search
result = search.instant_search(
    query=query,
    limit=10,
)
print(result.data)
```

Learn more about AI-Search and Oxylabs AI Studio Python SDK in our [PyPI repository](https://pypi.org/project/oxylabs-ai-studio/). You can also check out our [AI Studio JavaScript SDK](https://github.com/oxylabs/oxylabs-ai-studio-js) guide for JS users.

### Request Parameters

| Parameter                                            | Description                                       | Default Value |
| ---------------------------------------------------- | ------------------------------------------------- | ------------- |
| <mark style="background-color:green;">`query`</mark> | What to search for                                | –             |
| `limit`                                              | Maximum number of results to return (Maximum: 50) | 10            |
| `render_javascript`                                  | Enable JavaScript rendering                       | `False`       |
| `return_content`                                     | Whether to return markdown contents in results    | `True`        |
| `geo_location`                                       | Proxy location in ISO2 format                     | –             |

&#x20;    – mandatory parameters

**Note:** When `limit <= 10` and `return_content=False`, the search automatically uses the instant endpoint (`/search/instant`) which returns results immediately without polling, providing faster response times.

{% hint style="info" %}
**Note:** When `limit <= 10` and `return_content=False`, the search automatically uses the instant endpoint (`/search/instant`) which returns results immediately without polling, providing faster response times.
{% endhint %}

Instant search supported parameters:

| Parameter                                            | Description                                                                                                             | Default Value |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------- |
| <mark style="background-color:green;">`query`</mark> | What to search for                                                                                                      | –             |
| `limit`                                              | The maximum number of search results to return (Max: `10`)                                                              | `10`          |
| `geo_location`                                       | Google's canonical name of the location. See more [here](https://developers.google.com/google-ads/api/data/geotargets). | –             |

&#x20;    – mandatory parameters

### Output Sample

```python
[
  {
    "url": "https://www.spendwithpennies.com/easy-homemade-lasagna/",
    "title": "Easy Homemade Lasagna Recipe - Spend With Pennies",
    "description": "Rating 5.0 (3,349) · 1 hr 45 min This is the best LASAGNA RECIPE! Pasta, an easy meat sauce, and ricotta cheese are layered and then topped with more cheese before baking.",
    "content": null
  },
  {
    "url": "https://www.simplyrecipes.com/recipes/lasagna/",
    "title": "The Best Homemade Lasagna - Simply Recipes",
    "description": "Rating 4.9 (115) · 1 hr 45 min This classic lasagna recipe is made with an easy meat sauce as the base. Layer the sauce with noodles and cheese, then bake until bubbly!",
    "content": null
  },
  {
    "url": "https://www.seriouseats.com/12-lasagna-recipes-11808722",
    "title": "12 Must-Try Lasagna Recipes Featuring Crispy Edges and Gooey ...",
    "description": "Whether you have a taste for meaty classics like a lasagna alla Bolognese or an indulgent creamy vegetarian spinach lasagna, we've rounded up our favorite ...",
    "content": null
  },
  {
    "url": "https://bakerbynature.com/the-best-homemade-lasagna-recipe/",
    "title": "The Best Easy Homemade Lasagna Recipe - Baker by Nature",
    "description": "Rating 5.0 (71) · 2 hr 45 min Dec 12, 2025 · This is the ONLY lasagna recipe you'll ever need... from perfectly cooked noodles to rich tomato sauce and layers of cheese.",
    "content": null
  },
  {
    "url": "https://www.allrecipes.com/recipe/23600/worlds-best-lasagna/",
    "title": "World's Best Lasagna Recipe (with Video) - Allrecipes",
    "description": "Rating 4.8 (20,950) · 3 hr 15 min Feb 5, 2026 · This lasagna recipe from John Chandler is our most popular recipe! With sausage, ground beef, basil, and 3 types of cheese, it lives up to ...",
    "content": null
  }
]
```

## Practical use cases

AI-Search can be applied to a wide variety of data discovery and collection tasks:

1. **Search for latest news or articles on a topic –** Quickly gather up-to-date information, headlines, and summaries.
2. **Discover books, movies, or products –** Retrieve lists of items matching specific criteria or reviews.
3. **Research competitive offerings –** Find and analyze competitor pricing, features, and market positioning.
4. **Aggregate industry updates from multiple sites –** Compile relevant industry changes and trends into a single, structured feed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.oxylabs.io/products/ai-studio/ai-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.