Prompts

Prompts are the questions SurfacedBy asks AI platforms for a domain. The list endpoint returns the domain's active tracked prompts, pinned prompts first. Pinned is the same flag as pinning a prompt in the dashboard.

Listing is available on Professional and Agency. Adding and removing prompts are write operations and need an Agency key with the write scope, plus an Idempotency-Key header. A key acts with the current workspace role of the member who created it, so adding or removing a prompt also needs that member to be an editor or above today; otherwise the request returns 403 workspace_access_required.

Prompt object

Field	Description
`id`	Prompt id, used as `prompt_id`.
`domain_id`	The tracked domain.
`prompt`	The prompt text.
`language_code`	Recorded ISO 639-1 prompt language, or null for unclassified history.
`country_iso_2`	Recorded ISO alpha-2 market, or null for Global.
`user_pinned`	Whether the prompt is pinned.
`pinned_at`	When it was pinned, or null.
`source`	Who added the prompt: `added_by_you` when someone in your workspace added it (in the dashboard, through the API, or during setup), `suggested` when SurfacedBy suggested it.
`status`	`active` for every prompt in the list.
`search_volume`	Estimated monthly search volume, or null.
`ai_search_volume`	Statistical monthly demand estimate for this exact prompt, country and recorded language, or null. Derived from search-question data; it does not count observed assistant usage, visits or conversions. Numeric zero is a valid estimate only in the `estimated` state.
`ai_search_volume_state`	`estimated`, `no_estimate` (successful lookup with no estimate), `pending` (not looked up), `failed` (lookup failed), `unsupported` (unsupported prompt or scope), or `legacy_unknown` (historical provenance unavailable). Every state except `estimated` has a null value.
`cpc_usd`, `estimated_traffic_value_usd`, `monthly_value_usd`	Estimated cost per click, traffic value, and monthly value in US dollars, or null.
`sentiment`	Median score and modal label across valid scored answers mentioning your brand in the recorded prompt, country and language. Includes `score`, `label`, `responses_analyzed`, `low_data`, `measurement_state` and the recorded period. Fewer than 3 scored answers, or a missing, invalid, future or expired refresh period, leaves score and label null. A period expires 30 days after its captured end. Unscored answers never count as neutral.
`co_mentioned_brands`	Up to 5 source domains cited alongside yours in the recorded observation window. Empty when the period cannot establish current measurements.
`prompt_metrics_period`	`period_start`, `period_end`, `refreshed_at` and `is_current`. The start is 30 days before the captured end; `refreshed_at` records that same end, captured before paging saved answers. Retained dates describe an as-of window and do not mean the data was measured at request time.
`consecutive_uncited`	How many checks in a row tested this prompt without citing you.
`last_scanned_at`	When a check last tested this prompt, or null.
`created_at`	When the prompt was added.

Adding and removing

Adding a new prompt takes its text and language. The optional country targets a market; omitting it means Global:

{ "prompt": "best project management tool for small agencies", "language_code": "en", "country_iso_2": "US" }

The prompt joins the domain's tracked prompts as an active, pinned prompt. If the domain already tracks that text in the same country and language, that prompt is reactivated and pinned instead of duplicated. The response is 201 with the prompt object.

To pin an existing record, include its existing_id and prompt text. This preserves its recorded country and language, including unclassified history. A conflicting language is refused; an existing record is never reassigned to another language.

Two limits apply, the same as in the dashboard:

A domain can have at most 10 pinned prompts. Pinning another returns 409 pin_limit_reached, with current and limit in the body. Unpin one first.
A new prompt counts toward the workspace's prompt limit. At the limit, adding returns 409 prompt_limit_reached, with current and limit in the body. Pinning a prompt the domain already tracks takes no new slot.

Removing a prompt stops tracking it: it leaves the list and is no longer checked, and its past results stay in your history. It is more than unpinning. The response is {"id": "...", "deleted": true}. A prompt id that is not an active tracked prompt of the domain returns 404 not_found.

GET

/domains/{domain_id}/prompts

Path Parameters

`domain_id`
Required
Domain Id

Query Parameters

`cursor`Cursor

Header Parameters

`X-API-Key`X-Api-Key

curl -X GET "https://api.surfacedby.com/api/v1/ext/domains/string/prompts?cursor=string" \
  -H "X-API-Key: string"

Successful Response

null

POST

/domains/{domain_id}/prompts

Request Body

application/jsonRequired

`country_iso_2`Country Iso 2

ISO alpha-2 market; null means Global.

`existing_id`Existing Id

An existing prompt ID preserves its recorded country and language.

`language_code`Language Code

Recorded ISO alpha-2 prompt language. Required for new prompts.

`prompt`
Required
Prompt

Minimum length: 2Maximum length: 500

Path Parameters

`domain_id`
Required
Domain Id

Header Parameters

`X-API-Key`X-Api-Key

`Idempotency-Key`Idempotency-Key

curl -X POST "https://api.surfacedby.com/api/v1/ext/domains/string/prompts" \
  -H "X-API-Key: string" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "country_iso_2": "string",
    "existing_id": "string",
    "language_code": "string",
    "prompt": "string"
  }'

Successful Response

null

DELETE

/domains/{domain_id}/prompts/{prompt_id}

Path Parameters

`domain_id`
Required
Domain Id

`prompt_id`
Required
Prompt Id

Header Parameters

`X-API-Key`X-Api-Key

`Idempotency-Key`Idempotency-Key

curl -X DELETE "https://api.surfacedby.com/api/v1/ext/domains/string/prompts/string" \
  -H "X-API-Key: string" \
  -H "Idempotency-Key: string"

Successful Response

null

Path

Query

Headers

domain_idRequiredDomain Id

cursorCursor

X-API-KeyX-Api-Key

Response

TypeScript

Path

Headers

Body

country_iso_2Country Iso 2

existing_idExisting Id

language_codeLanguage Code

promptRequiredPrompt

domain_idRequiredDomain Id

X-API-KeyX-Api-Key

Idempotency-KeyIdempotency-Key

Response

TypeScript

Path

Headers

domain_idRequiredDomain Id

prompt_idRequiredPrompt Id

X-API-KeyX-Api-Key

Idempotency-KeyIdempotency-Key

Response

TypeScript

On this page

`domain_id`
Required
Domain Id

`cursor`Cursor

`X-API-Key`X-Api-Key

`country_iso_2`Country Iso 2

`existing_id`Existing Id

`language_code`Language Code

`prompt`
Required
Prompt

`domain_id`
Required
Domain Id

`X-API-Key`X-Api-Key

`Idempotency-Key`Idempotency-Key

`domain_id`
Required
Domain Id

`prompt_id`
Required
Prompt Id

`X-API-Key`X-Api-Key

`Idempotency-Key`Idempotency-Key