---
title: "Update Prompt Status"
method: PATCH
path: "/{brand_id}/prompts/{prompt_id}"
---

# Update Prompt Status

`PATCH /{brand_id}/prompts/{prompt_id}`

## Request

- Base URL: `https://api.scrunchai.com/v1`
- URL: `https://api.scrunchai.com/v1/{brand_id}/prompts/{prompt_id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/scrunch/apis/scrunch-data-api/docs/:brand_id/prompts/:prompt_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Pauses or resumes a prompt. Requires the `configure` scope.

**Pausing** (`status: paused`) stops collection for the prompt and releases its variants from the organization's prompt pool. The prompt keeps its configuration and all of its collected history, and stays readable through `GET /{brand_id}/prompts?status=paused`.

**Resuming** (`status: active`) restores the exact deployment the prompt had when it was paused and re-checks the prompt pool, so it can return `429 quota_exceeded` when the organization no longer has room for the prompt's variants.

Both transitions are idempotent: a prompt already in the requested status returns `200` with the prompt, unchanged.

A transition the prompt's status does not allow (resuming an archived prompt, resuming one whose persona is archived) returns `409` with a `type` naming the reason. To archive a prompt, use `DELETE /{brand_id}/prompts/{prompt_id}` instead.

## Path parameters

- `brand_id` integer, required: The unique identifier for the brand
- `prompt_id` integer, required: The unique identifier for the prompt to update

## Request body

- APIPromptPatchInput: Body of the prompt PATCH. `status` is the only mutable field - a prompt's text, platforms and labels are fixed at create time.
  - `status` 'active' | 'paused', required: The lifecycle status to move the prompt to. - `paused` - stop collecting for this prompt and release its variants from the organization's prompt pool; its configuration and history are kept - `active` - resume collecting with the exact deployment the prompt had when it was paused `archived` is not accepted here - archive a prompt with `DELETE /{brand_id}/prompts/{prompt_id}`.

## Response `200`

The prompt after the transition. Also returned when the prompt was already in the requested status.

- PromptListing: Represents a prompt being tracked for AI visibility, including its configuration and metadata.
  - `id` integer, required: Unique identifier for the prompt
  - `text` string, required: The prompt text being tracked
  - `stage` string, required: The customer journey stage this prompt represents. Returned as the display name of the brand's active stage — one of the brand's default set (`Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other` for intent brands; `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other` for funnel brands) or a custom stage name.
  - `persona_id` integer, nullable, required: ID of the associated persona, if any
  - `platforms` string[], required: AI platforms this prompt is tracked on
  - `tags` string[], required: Custom tags assigned to this prompt
  - `topics` string[], required: Auto-detected or assigned topics for this prompt
  - `status` 'active' | 'paused' | 'archived', required: Lifecycle status of the prompt (`active`, `paused`, or `archived`)
  - `created_at` string, date-time, required: Timestamp when the prompt was created

## Other responses

- `404`: Not found. `detail.type` is `prompt_not_found` when no prompt with this ID exists for this brand, or `brand_not_found` when the brand no longer exists.
- `409`: The prompt's current state does not allow the requested transition. `detail.type` names the reason: - `is_archived` - archived prompts cannot be paused or resumed - `persona_archived` - the prompt's persona is archived; `detail.blocking_persona_ids` lists the personas to restore or reassign before resuming - `active_duplicate` - an active prompt with the same text, persona and country already exists - `no_active_variants` - the prompt has no active variants, so resuming it would collect nothing
- `422`: Validation error. `status` accepts only `active` or `paused`, and no other field is accepted in the body.
- `429`: The organization's prompt pool has no room for the prompt's variants. Returns the `quota_exceeded` error envelope.
- `503`: The transition did not complete (`detail.type` is `pause_failed` or `resume_failed`). Retry the request.

## Changes

- **2026-11-03** `e37811b6bc07`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scrunch/apis/scrunch-data-api/changes/:brand_id/prompts/:prompt_id/patch.md)

---

[API](https://skmtc.dev/scrunch/apis/scrunch-data-api.md) - [All operations](https://skmtc.dev/scrunch/apis/scrunch-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scrunch/apis/scrunch-data-api/revisions/3c6aa69a6595?raw)