---
title: "Web Search"
method: POST
path: "/api/v1/search"
---

# Web Search

`POST /api/v1/search`

## Request

- Base URL: `https://api.mesharc.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mesharc.dev/api/v1/search`
- Auth: none declared

Web results for a query: Google's results page read through the
ladder, Bing's when Google refuses. Organic results only -- title, URL,
snippet -- each saying which engine it came from.

Waits for the results like a one-URL /scrape -- up to `timeout` seconds
(60 by default, 120 at most), then 202 with the id to poll at
GET /search/{id}. `scrape` hands the results' URLs to a batch, and each
result gains its page as it lands. A refused results page is free; the
same search within the hour is answered from the last one at no charge.

`webhook` (a URL, or {url, events, metadata}) is told once how the
search ended -- `search.completed` or `search.failed`, an answer from
the cache included -- signed with `webhookSecret`, returned here only.

## Headers

- `authorization` string, nullable
- `x-mesharc-tenant` string, nullable

## Request body

- MesharcApiRoutesSearchRequest2
  - `query` string, required
  - `limit` integer, nullable
  - `sources` string[], nullable
  - `page` integer, nullable
  - `country` string, nullable
  - `lang` string, nullable
  - `freshness` string, nullable
  - `includeDomains` string[], nullable
  - `excludeDomains` string[], nullable
  - `scrape` SearchScrape
    - `formats` string[]
    - `maxCredits` integer, nullable
  - `timeout` number, nullable
  - `destination` string, nullable
  - `webhook` union
    - object
    - string

## Response `200`

Successful Response

- SearchResponse
  - `id` string, required
  - `kind` string, required
  - `status` string, required
  - `query` string, required
  - `params` object, required
  - `data` SearchResultOut[], required
    - `position` integer, required
    - `url` string, required
    - `title` string, required
    - `snippet` string, required
    - `source` string, required
    - `engine` string, required
    - `publisher` string, nullable
    - `age` string, nullable
    - `page` object, nullable
  - `engine` string, required
  - `rung` string, required
  - `cached` boolean, required
  - `batchId` string, nullable
  - `creditsUsed` integer, required
  - `attempts` SearchAttempt[], required
    - `engine` string, nullable
    - `ok` boolean, nullable
    - `reason` string, nullable
    - `rung` string, nullable
    - `verdict` string, nullable
    - `credits` integer, nullable
  - `next` string, nullable
  - `error` string, required
  - `createdAt` string, nullable
  - `finishedAt` string, nullable
  - `request_id` string, required
  - `webhookSecret` string, nullable

## Other responses

- `422`: Validation Error

---

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