# Prompts

The questions we run against the AI models every week, and the execution records each run produces.

### GET `/dimensions/prompts`

Lists prompts in a project.

Params:

- `project_id` required
- `collection_id`
- `prompt` prompt ID
- `country_code`
- `language_code`
- `from`
- `to`
- `page`
- `per_page` ≤ 100

### GET `/dimensions/prompt_executions`

Lists prompt executions in a project.

Params:

- `project_id` required
- `model`
- `collection_id`
- `prompt` prompt ID
- `country_code`
- `language_code`
- `from`
- `to`
- `page`
- `per_page`
- `mention_filter`
- `citation_filter`
- `competitors` the two-axis matrix described under `GET /answers`

### GET `/dimensions/query_fan_outs`

The sub-queries a model actually issued when answering your tracked prompts, useful for finding the phrasing models search for rather than the phrasing you wrote. `view=query` (default) returns one row per distinct sub-query with its count and share of all occurrences; `view=prompt` returns one row per prompt with how many distinct sub-queries it produced. Fan-out is reported mainly by ChatGPT, so an empty result usually means the models in scope do not expose it.

Params:

- `project_id` required
- `view` `query` or `prompt`
- `query` substring on the sub-query text
- `order`
- `direction`
- `model`
- `collection_id`
- `prompt`
- `country_code`
- `language_code`
- `prompt_type`
- `brand_kind`
- `range`
- `from`
- `to`
- `page`
- `per_page`
- `output`

### POST `/prompts`

Create up to 100 prompts per request. Existing prompts (same text + locale) are skipped.

Body (JSON):

- `project_id` required
- `prompts` array, required, max 100
- `country_code` required
- `language_code` required

### DELETE `/prompts/:id`

Delete a prompt. Irreversible; the prompt disappears immediately, frees a prompt slot, and its history (executions, mentions, citations, sentiment) is purged by a background job. Requires a writable API key.

Params:

- `project_id` required
- `:id` in URL

Returns `ERR_NOT_FOUND` for prompts outside the project.