---
title: "Create a cluster from a search or from a list of domains"
method: POST
path: "/v1/clusters"
tags: ["clusters"]
---

# Create a cluster from a search or from a list of domains

`POST /v1/clusters`

## Request

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

From a search ('query'): the results up to the plan's limits become the cluster; it costs one search. From a list ('domains'): names or urls, only sites in the index are kept; costs nothing. The plan caps the size of a cluster. With 100 clusters on the account the answer is 409 cluster_limit - nothing is deleted.

## Request body

- CreateClusterRequest
  - `query` string: A search in the website's syntax; its results become the cluster.
  - `domains` union: Names or urls to put into the cluster. Use either this or query.
    - string[]
    - string: One name per line.
  - `name` string

## Response `201`

The new cluster.

- Cluster
  - `id` integer, required
  - `name` string, required
  - `size` integer, required: Number of domains.
  - `created` string, date-time, required
  - `submitted` integer: From a list: how many names were sent.
  - `max_size` integer: The plan's cap on domains per cluster.
  - `query` string
  - `total` integer: From a search: results the search found.
  - `index_complete` boolean
  - `query_note` string
  - `operation` 'and' | 'or' | 'diff'
  - `from` integer[]

## 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`: No paid plan (plan_required).
- `409`: The account already has 100 clusters (cluster_limit).
- `429`: Too many requests, or the daily search or extraction allowance is used up.

---

[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)