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

# Web Search

> Search the web and get structured results instantly

## Overview

Synchronous web search. Returns results immediately — no polling needed.

## Authentication

Requires x402 payment proof in the `X-Payment-Proof` header.

## Request Body

<ParamField body="query" type="string" required>
  Search query (1-500 characters)
</ParamField>

<ParamField body="max_results" type="integer" default={5}>
  Maximum number of results to return (1-20)
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200)

<ResponseField name="data.query" type="string">
  The search query
</ResponseField>

<ResponseField name="data.results" type="array">
  Array of search results, each with `url`, `title`, and `description`
</ResponseField>

<ResponseField name="data.result_count" type="integer">
  Number of results returned
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/search \
    -H "Content-Type: application/json" \
    -H "X-Payment-Proof: <your_x402_signature>" \
    -d '{
      "query": "best AI agent frameworks 2026",
      "max_results": 5
    }'
  ```

  ```typescript SDK theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  const results = await agent.webSearch({
    query: "best AI agent frameworks 2026",
    max_results: 5,
  });

  for (const result of results.data.results) {
    console.log(`${result.title}: ${result.url}`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "query": "best AI agent frameworks 2026",
      "results": [
        {
          "url": "https://example.com/ai-frameworks",
          "title": "Top AI Agent Frameworks in 2026",
          "description": "A comprehensive comparison of the leading AI agent frameworks..."
        },
        {
          "url": "https://example.com/langchain-vs-crewai",
          "title": "LangChain vs CrewAI: Which Framework to Choose",
          "description": "An in-depth comparison of two popular agent frameworks..."
        }
      ],
      "result_count": 2
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) for web search costs.</Info>

## Notes

* Results are returned synchronously (no job polling)
* 15-second timeout per request