---
title: "Find websites whose page source contains a code fragment"
method: GET
path: "/v1/search"
tags: ["search"]
---

# Find websites whose page source contains a code fragment

`GET /v1/search`

## Request

- Base URL: `https://api.publicwww.com`
- URL: `https://api.publicwww.com/v1/search`
- Auth: HTTP bearer

Results are websites ranked by popularity. Bulk is this endpoint with a large per_page (up to the plan's row limit, see /v1/account); the answer streams as it is produced. A plan covers the first max_per_page rows of a query: page * per_page may not exceed it.

## Query parameters

- `query` string, required
- `page` integer
- `per_page` integer
- `snippets` boolean
- `format` 'json' | 'ndjson' | 'xml' | 'csv' | 'tsv' | 'txt'
- `columns` string
- `delimiter` string
- `header` boolean

## Response `200`

Search results. The body follows format; the totals are also in the headers.

- SearchResponse
  - `query` string, required
  - `page` integer, required
  - `per_page` integer, required
  - `total` integer, required: Websites matching the query in the index.
  - `total_pages` integer, required
  - `returned` integer, required: Rows in this answer.
  - `truncated` boolean, required: true when the plan cut this page short.
  - `index_complete` boolean, required: false when part of the index did not answer in time; the results may be incomplete.
  - `took_ms` integer, required
  - `query_note` string: Present when the query could not be run as written, with the reason.
  - `results` SearchResult[], required
    - `domain` string
    - `url` string: The page the match was found on.
    - `rank` integer, nullable: Popularity rank, 1 is the most popular; null for an unranked website.
    - `ranked` boolean
    - `snippets` Snippet[]: Only with snippets=1. Up to 5 fragments of page source around the match.
      - `text` string, required: The fragment of page source.
      - `match` string, required: The part of text that matched the query.

## Other responses

- `400`: The request cannot be served as asked: missing_query, unknown_format, unknown_column, format_not_available, per_page_too_large, page_too_deep, invalid_json.
- `401`: missing_key - no Authorization: Bearer header; invalid_key - the token does not name an account.
- `403`: plan_required - the account has no paid plan.
- `429`: too_many_requests - more than 10 requests a minute, wait Retry-After seconds; quota_exceeded - the day's searches are used up, searches with snippets included; snippet_quota_exceeded - the day's snippet searches are used up, searching without snippets still works.

---

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