---
title: "Web search"
method: POST
path: "/v1/tools/web_search"
---

# Web search

`POST /v1/tools/web_search`

## Request

- Base URL: `https://unstuckapi.com`
- URL: `https://unstuckapi.com/v1/tools/web_search`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Search the web and get the top results (title, URL, snippet) as clean JSON. Live Google results, any country or city. Use when you need current information, sources, or links.

Price: $0.01 per call. Charged once per call that returns a result, including an empty result list. Failed calls are free.

## Request body

- object
  - `query` string, required: What to search for.
  - `location` string: Country or place to search from, e.g. "Houston, TX". Default "United States" (or the connection's default location).
  - `num` integer: How many results, default 10, max 20.

## Response `200`

Success

- object
  - `tool` 'web_search', required
  - `result` object, required
    - `query` string, required
    - `location` string, required: Location searched from.
    - `results` object[], required
      - `position` number, required: Rank among organic results, 1 = top.
      - `title` string, nullable, required
      - `url` string, nullable, required
      - `domain` string, nullable, required
      - `snippet` string, nullable, required
  - `charged_usd` number, required
  - `balance_usd` number, required

## Other responses

- `400`: Invalid JSON or input. Not charged.
- `401`: Paid tool without a valid API key.
- `402`: Balance too low for this call. Not charged.
- `404`: Unknown tool.
- `422`: The tool failed. Not charged.
- `429`: Rate limited, free tries used up, or the uncharged-result limit reached. See Retry-After.

---

[API](https://skmtc.dev/unstuckapi/apis/unstuck-api.md) · [All operations](https://skmtc.dev/unstuckapi/apis/unstuck-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unstuckapi/apis/unstuck-api/revisions/ef3ec951224f?raw)