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.
On this page 8 sections
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:
vibiz search "latest developments in solid state batteries" --limit 3You can also run the underlying action directly with JSON input:
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:
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:
{
"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.
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:
vibiz scrape https://example.com/typescript-5-5The 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 or learn how to crawl a whole site to markdown for 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 or explore the broader Web data: scrape, search, SEO, ads library 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:
vibiz runs --action web.search --since 1dTo fetch the exact output and input payload of a specific run:
vibiz runs arun_98a72bSearch 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.