---
title: "Ask the AI for page groups, keyword clusters and brand terms"
method: POST
path: "/v1/sites/{site}/search/segment-proposals"
tags: ["gsc"]
---

# Ask the AI for page groups, keyword clusters and brand terms

`POST /v1/sites/{site}/search/segment-proposals`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/sites/{site}/search/segment-proposals`
- Auth: HTTP bearer

Ask Frontshelf's AI to suggest page groups, keyword clusters and brand terms for a site from its Search Console data (the top queries and pages of the last 90 days and the segments it already has). It starts one run and answers the run's current `state` (queued, running, succeeded, failed or cancelled) and `run_id`. Send an `idempotency_key` and reuse it on a retry: the same key answers the same run's state now, never a second run (without one, every call is a new request); one run at a time per site. Nothing is written: every suggestion waits in gsc_proposals_list for an accept or a dismiss. Fair use is pooled across the workspace over 30 days: past it, RATE_LIMITED with `details.resets_at` (groups and clusters can still be made with gsc_segments_save). A property with too few queries or pages is refused with its count. Paid (segments): on a site that is not paid for, BILLING_REQUIRED.

## Path parameters

- `site` string, required: Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID.

## Headers

- `Idempotency-Key` string: Any unique string per intended change; a retry with the same key answers the first call's result.

## Request body

- object
  - `source_id` string: One of the site's Search Console properties (ssrc_…, from gsc_sources_list). Omit for the site's primary property.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `202`

Ask the AI for page groups, keyword clusters and brand terms

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `site_id` string, required: The site's canonical id.
  - `state` string, required: The run's state now: queued, running, waiting, succeeded, failed or cancelled.
  - `run_id` string, required

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `402`: BILLING_REQUIRED
- `403`: ORGANIZATION_FROZEN, SCOPE_DENIED
- `404`: SITE_NOT_FOUND, NOT_FOUND
- `409`: AMBIGUOUS_SITE, SEARCH_NOT_CONNECTED, SEARCH_NOT_READY, IDEMPOTENCY_CONFLICT, INVALID_TRANSITION, AGENT_STOPPED
- `429`: RATE_LIMITED
- `503`: PLATFORM_READ_ONLY, DEPENDENCY_UNAVAILABLE

---

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