# A web search API for AI agents and apps

> Give AI agents and LLMs real-time web search with one API call, structured JSON outputs, recency filters, and per-call cost tracking.

**You can give an AI model or agent live web search using the `web.search` action via REST API, CLI, or code.** Calling the endpoint returns structured JSON with page titles, URLs, relevant snippets, source categories, and publication dates. This allows your language models to ground their answers in current data without parsing messy HTML or managing browser sessions.

When an LLM works strictly from its training weights, it cannot answer questions about today's events, fresh product releases, or shifting documentation. Adding search gives the model an on-demand retrieval tool. This guide covers how the web search action works, how to configure filters, and how to connect it to an agent loop.

## Why AI agents need clean search results

Standard search engines build results for human eyes: ad blocks, tracking redirects, and heavy visual styling. When you feed raw search result pages into a context window, you waste thousands of tokens on navigation menus, cookie disclosures, and styling scripts.

AI agents require:

- **Structured output.** Models parse key-value pairs reliably. Clean arrays of titles, snippets, and clean target URLs keep tool outputs compact.
- **Low latency.** Search sits directly in the model's generation loop. Long pauses stall the entire conversation.
- **Predictable budgets.** Agent loops can spin through dozens of searches if left unchecked. Per-call accounting prevents surprise charges.
- **Data boundaries.** LLM frameworks must receive external web text purely as data, never as execution instructions.

The `web.search` action handles querying the web synchronously and returns only the core information an LLM requires to answer a user prompt.

## How to run a web search using the CLI and HTTP

You can test search queries from your terminal or invoke the endpoint from any programming language.

From the command line:

```bash
vibiz search "latest developments in solid state batteries" --limit 3
```

You can also run the underlying action directly with JSON input:

```bash
vibiz run web.search --input '{"query":"fastest growing open source ai projects","recency":"month","limit":5}'
```

To call search over HTTP, make a `POST` request to `/v1/actions/web.search` using your bearer token:

```bash
curl https://thelastapi.dev/v1/actions/web.search \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "query": "release notes for typescript 5.5",
      "limit": 3,
      "sources": ["web"],
      "recency": "month"
    }
  }'
```

The server returns an `action_result` object containing the results, execution metadata, and cost:

```json
{
  "object": "action_result",
  "action": "web.search",
  "output": {
    "results": [
      {
        "title": "Announcing TypeScript 5.5",
        "url": "https://example.com/typescript-5-5",
        "snippet": "TypeScript 5.5 introduces inferred type predicates, regex syntax checking, and performance improvements across the compiler...",
        "source": "web",
        "date": "2024-06-20"
      }
    ]
  },
  "cost_micro_usd": 2000,
  "run_id": "arun_98a72b",
  "console_url": "https://thelastapi.dev/web-data?action=web.search&run=arun_98a72b"
}
```

The response includes the exact cost in micro-dollars (`cost_micro_usd`), allowing your system to log spending for each retrieval query.

## Search parameters and configuration

The `web.search` action accepts several optional parameters to shape the results according to what your agent needs:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | *required* | The search phrase (up to 400 characters). |
| `limit` | integer | `5` | Number of results to return (between 1 and 20). |
| `sources` | array | `["web"]` | Target sources: can include `"web"` and `"news"`. |
| `recency` | string | none | Limits results by time: `"day"`, `"week"`, `"month"`, or `"year"`. |
| `location` | string | none | Country or geographic focus for regional queries. |

Setting `recency: "day"` or `recency: "week"` is useful when building morning news summaries or market intelligence monitors where old articles pollute the prompt.

## Adding search to an LLM tool call

In an application built with TypeScript, you can run search directly through `@vibiz/app` inside a tool definition. For more background on structuring agent workflows, see our guide on how to [give an agent web research tools: search, scrape and crawl](https://thelastapi.dev/blog/agent-web-research-tools).

```ts
import { vibiz } from '@vibiz/app';

// Define a function that an AI tool call can execute
async function searchWebTool(query: string, recency?: 'day' | 'week' | 'month' | 'year') {
  const result = await vibiz.actions.run('web.search', {
    query,
    limit: 5,
    recency,
    sources: ['web'],
  });

  // Extract snippets and links for the LLM's context
  return result.output.results.map((item) => ({
    title: item.title,
    url: item.url,
    snippet: item.snippet,
    date: item.date,
  }));
}
```

If your agent runs on an MCP-compatible client like Cursor or Claude Code, the agent can call `vibiz_run_action` with `name: "web.search"` and pass the JSON input directly. Agents can also inspect past executions using `vibiz_action_runs` to avoid searching for the exact same query twice in a single session.

Always remind your agent system prompts that search output represents third-party data from the public web. It must treat snippets as external information, not instruction overrides.

## From snippet to full page: pairing search with scraping

Snippets give an LLM a fast overview, but complex queries often demand deeper reading. For example, an agent researching technical errors or library upgrades needs the code blocks inside the documentation page, not just a two-sentence preview.

You can chain search directly into the `web.scrape` action. The agent searches for the relevant guide, inspects the top URL, and passes that URL to `web.scrape` to retrieve the body as clean markdown:

```bash
vibiz scrape https://example.com/typescript-5-5
```

The scraper strips scripts, ads, and navigational clutter, returning clean markdown formatted for model consumption. For a detailed walkthrough of that workflow, read how to [scrape a website to markdown with one API call](https://thelastapi.dev/blog/scrape-website-to-markdown-api) or learn how to [crawl a whole site to markdown for RAG](https://thelastapi.dev/blog/crawl-site-markdown-rag).

## Choosing between web search and SEO SERP data

thelastapi provides two different endpoints for reading the web: `web.search` and `seo.serp`. While both return search links, they address different use cases.

| Feature | `web.search` | `seo.serp` |
| --- | --- | --- |
| **Primary purpose** | General answers, research, news summaries | Search rank tracking, competitor analysis |
| **Data source** | Index of web and news pages | Live Google search result pages |
| **Result details** | Title, URL, snippet, source, date | Position, rank type, domain, title, snippet, SERP features |
| **SERP Features** | No | Yes (People Also Ask, AI Overviews, videos) |
| **Typical cost** | Fraction of a cent | Fraction of a cent |
| **Depth** | 1 to 20 results | 10 to 100 positions |

Use `web.search` when your agent needs quick facts, recent news, or reference links to cite in conversation. Use `seo.serp` when you are analyzing which competitors occupy the top blue links for specific target keywords. You can read more about keyword performance in our guide on [a keyword research API: search volume, CPC and competition](https://thelastapi.dev/blog/keyword-research-api-volume-cpc) or explore the broader [Web data: scrape, search, SEO, ads library](https://thelastapi.dev/docs/actions) documentation.

## Run history, costs, and safety limits

Every search call is logged. You can review past runs in the console under **Web data** or list them through the CLI:

```bash
vibiz runs --action web.search --since 1d
```

To fetch the exact output and input payload of a specific run:

```bash
vibiz runs arun_98a72b
```

Search calls run synchronously and settle in a few hundred milliseconds. If an external lookup stalls past the system limit, the action halts and returns a `503 provider_unavailable` error with `details.reason: "timeout"`.

Search costs are billed as a fraction of a cent per call plus the standard 30% web data margin, drawn directly from your account credits. Every call counts toward your daily account ceiling ($5 by default). If your agent enters a recursive loop and exhausts the daily limit, subsequent requests return `429 rate_limited` until midnight UTC, protecting your account from uncontrolled billing spikes.

To get started, generate your key, test a query using `vibiz search "hello world"`, and attach the action to your model's tool schema.

## Frequently asked questions

### What happens if a web search query exceeds 400 characters?

The API rejects the request with an `invalid_request` (HTTP 400) status and specifies the problematic field in `details.field`. Keep your search queries concise and strip unnecessary conversational filler before sending them.

### Can the search API filter results by publication date?

Yes. You can provide the `recency` parameter with a value of `day`, `week`, `month`, or `year` to restrict results to pages indexed within that timeframe.

### How much does each web search call cost?

A search query costs a fraction of a cent. Each response returns the exact cost in `cost_micro_usd`, which is billed against your credits plus a 30% platform margin.

### How do I avoid duplicate searches in an autonomous agent loop?

Your agent can call `vibiz_action_runs` or query `GET /v1/actions/runs?action=web.search` to inspect prior queries and outputs before executing a new search request.

---

Published 2026-11-15 · https://thelastapi.dev/blog/web-search-api-ai-agents
