---
title: "Generate prompt suggestions"
method: POST
path: "/prompt_generations"
tags: ["Prompts"]
---

# Generate prompt suggestions

`POST /prompt_generations`

## Request

- Base URL: `https://api.llmpulse.ai/api/v1`
- URL: `https://api.llmpulse.ai/api/v1/prompt_generations`
- Auth: API key in header `Authorization`

Starts a suggestion run with one of the generators behind the app's Add prompts wizards and answers 202 with the run. website writes suggestions from the scraped website (80% non-brand, 20% brand; up to 100 per project, then ERR_LIMIT_REACHED), keyword from a keyword or the project profile (optionally around a competitor), topic from a topic, reddit from Reddit discussions of a topic or brand, paa from Google People Also Ask (up to 5 keywords, counted against the account's 24-hour lookup allowance), reputational from brand reputation questions, translate from the project's prompts of another locale, search_console from the connected property's top queries of the last 28 days (Growth plan or above, ERR_PLAN_REQUIRED). The suggestions land in the Suggested prompts queue; poll GET /prompt_generations/{id}, then accept the ones you want with POST /suggested_prompts/accept. Nothing is tracked until accepted. The request is validated before the run starts, and refused with ERR_LIMIT_REACHED when the plan has no prompt slot left, ERR_INVALID_PARAM with error.meta.reason pitch_prompts_frozen for a launched pitch project, whose prompts are fixed, or ERR_QUOTA_EXCEEDED after 60 runs in an hour (the per-user prompt suggestion allowance, shared with project setup). Requires a `read_write` scope API key and, for team members, create access to Prompts.

## Request body

- PromptGenerationRequest
  - `project_id` integer, required
  - `source` 'website' | 'keyword' | 'topic' | 'reddit' | 'paa' | 'reputational' | 'translate' | 'search_console', required: Which Add prompts generator to run
  - `query` string: keyword: optional keyword or research query. topic and reddit: required topic (reddit: the brand when search_type=brand). paa: one keyword, as an alternative to keywords.
  - `count` integer: keyword and topic: how many suggestions to ask for, capped by the prompt slots left
  - `country_code` string: ISO 3166-1 alpha-2 country of the suggestions (default the project country)
  - `language_code` string: ISO language code of the suggestions (default the project language)
  - `competitor_id` integer: keyword: write the suggestions around this competitor of the project
  - `search_type` 'topic' | 'brand': reddit: search discussions of a topic or a brand
  - `keywords` string[]: paa: up to 5 keywords; each is a People Also Ask lookup counted against the account's 24-hour allowance
  - `source_country_code` string: translate: country of the prompts to translate
  - `source_language_code` string: translate: language of the prompts to translate
  - `min_words` integer: search_console: skip queries shorter than this many words
  - `all_countries` boolean: search_console: include queries from every country instead of country_code only
  - `property` string: search_console: the property id to read queries from (GET /search_console/properties lists them); the primary property when omitted

## Response `202`

The run, status processing

- PromptGenerationResponse
  - `id` string, uuid, required: The run id; poll GET /prompt_generations/{id} with it (kept for 24 hours)
  - `project_id` integer, required
  - `source` string, required
  - `status` 'processing' | 'completed' | 'failed', required
  - `params` object, required: The validated request the run uses, with the project's locale filled in
    - `country_code` string
    - `language_code` string
    - `query` string
    - `count` integer
    - `competitor_id` integer
    - `search_type` string
    - `keywords` string[]
    - `source_country_code` string
    - `source_language_code` string
    - `min_words` integer
    - `all_countries` boolean
    - `property` string
  - `created_at` string, date-time, required
  - `finished_at` string, date-time, nullable, required
  - `suggestions_count` integer, required
  - `suggestions` SuggestedPrompt[], required: The suggestions the run saved to the Suggested prompts queue, with their current status
    - `id` integer, required
    - `prompt` string, required
    - `source` string, required: The generator that wrote it: website, magic (keyword runs), topic, reddit, paa, reputational, translate, gsc (Search Console) or catalog
    - `status` string, required: pending, accepted or rejected
    - `country_code` string, nullable, required
    - `language_code` string, nullable, required
    - `prompt_id` integer, nullable, required: The prompt an accepted suggestion became
    - `accepted_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
  - `error` object, nullable, required: Why a failed run failed
    - `code` string, required: ERR_GENERATION_FAILED, ERR_NOT_FOUND (no suggestions came back), ERR_QUOTA_EXCEEDED, or a Search Console error code
    - `message` string, required
  - `request_id` string, required

## Other responses

- `403`: API key lacks write permission
- `404`: Resource not found
- `422`: Invalid parameters

## Changes

- **2026-10-16** `dd090b1e1154`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/llmpulse/apis/llm-pulse-api/changes/prompt_generations/post.md)

---

[API](https://skmtc.dev/llmpulse/apis/llm-pulse-api.md) - [All operations](https://skmtc.dev/llmpulse/apis/llm-pulse-api/llms.txt) - [OpenAPI document](https://skmtc.dev/llmpulse/apis/llm-pulse-api/revisions/38a31f123641?raw)