> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get prompt suggestions

> Read the latest Prompt Studio generation for a workspace: the 20 recommendations by default, more of the scored pool with limit, and the pool size.

Returns the latest Prompt Studio generation for the workspace. Suggestions come
in order: the 20 recommendations first, then the rest of the scored pool. By
default the response contains the 20 recommendations. Set `limit` to read more
of the pool, up to 500 suggestions; `total` gives the size of the whole pool.
When no generation exists yet, `run` is absent and `suggestions` is an empty array; start one with
[Generate prompt suggestions](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/generate.md).

Available on Growth, Agency Growth, Business, Agency Business and Enterprise plans. See [Authentication](https://docs.qwairy.co/developers/authentication.md).

**Authorization** `string` *required*

Bearer token for your team.

**brandId** `string` *required*

Workspace identifier. The workspace must belong to the token's team.

**focus** `string` (default: balanced)

`balanced`, `DISCOVERY`, `CONSIDERATION`, `PERCEPTION` or `AUTHORITY`.

**limit** `integer` (default: 20)

Maximum number of suggestions returned, recommendations first. An integer from 1 to 500.

## Response

**run** `object`

The generation these suggestions come from. Absent when no generation exists yet. Same fields as
[Get a suggestion generation](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/get-run.md).

**focus** `string`

The focus applied to the ordering

**total** `integer`

Number of suggestions in the whole pool for this focus, whatever the limit

**suggestions** `array`

The recommendations first, then the rest of the pool, cut at `limit`.

**Suggestion**

**id** `string`

Suggestion identifier, used by [Accept prompt suggestions](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/accept.md)

**text** `string`

Suggested prompt text

**topic** `string | null`

Suggested topic name

**keywordId** `string | null`

Existing topic identifier, when the suggested topic is already configured

**funnelStage** `string | null`

Funnel stage of the prompt

**intent** `string | null`

Search intent of the prompt

**score** `integer`

Suggestion score from 0 to 100

**reason** `string | null`

Why the prompt was suggested

**recommended** `boolean`

Whether the suggestion is one of the 20 recommendations

**tracked** `boolean`

`true` when an equivalent prompt is active and monitored. An equivalent archived or paused prompt reads `false`: accepting the suggestion reactivates that prompt and reports `created`

## Synthetic request and response

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/$BRAND_ID/prompt-suggestions?focus=DISCOVERY&limit=1" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

```json theme={null}
{
  "run": {
    "id": "bbbbbbbb-0000-4000-8000-000000000000",
    "status": "COMPLETED",
    "source": "manual",
    "keywordId": null,
    "recommendations": 20,
    "createdAt": "2026-10-12T09:00:00.000Z",
    "completedAt": "2026-10-12T09:02:00.000Z"
  },
  "focus": "DISCOVERY",
  "total": 48,
  "suggestions": [
    {
      "id": "cccccccc-0000-4000-8000-000000000000",
      "text": "Which CRM tools support small sales teams?",
      "topic": "CRM software",
      "keywordId": null,
      "funnelStage": "TOFU",
      "intent": "Discovery",
      "score": 88,
      "reason": "Covers a common comparison question for the category.",
      "recommended": true,
      "tracked": false
    }
  ]
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_PARAMETER` | `focus` is not one of the listed values, or `limit` is not an integer from 1 to 500 |
| `401` | Flat body | Missing or invalid token |
| `403` | `INSUFFICIENT_PLAN` | Generic plan refusal: "This endpoint is not included in the team's plan." |
| `404` | `BRAND_NOT_FOUND` | The workspace is missing or inaccessible |

Read errors use the flat or nested shapes described in [Error codes](https://docs.qwairy.co/developers/errors.md). On `429`, honor `Retry-After`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.