Signal API
Suggested prompts as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Suggested prompts

Review, track, or dismiss prompt suggestions generated from visibility evidence.

API scopeThese endpoints are available at both scopes.
Choose the resource whose data you want to manage.Learn about scopes →

Your selection updates every endpoint path, path parameter, and example on this page.

GET
project/projects/{project_id}/visibility/suggested_prompts

Returns paginated diagnosis- and fanout-sourced prompt suggestions for the selected project. Suggestions are separate from tracked prompts and consume no capacity.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

qstring

Search suggestion content, reason, and topic name.

Optional
statussuggested | tracked | dismissed | expired

Suggestion lifecycle state to return.

OptionalDefault: suggested
pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Suggestions per page. Maximum: 100.

OptionalDefault: 20
Response

Response envelope

project_id:uuidsuggested_prompts:SuggestedPrompt[]pagination:Pagination
project_iduuid

Resolved Ceyo project identifier.

suggested_promptsSuggestedPrompt[]

Suggestions matching the selected status and search.

paginationPagination

Suggestion pagination metadata.

Object

SuggestedPrompt

iduuid

Suggested prompt identifier.

topic_iduuid

Existing topic selected for the suggestion.

topic_namestring

Current name of the selected topic.

contentstring

Suggested prompt question.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt intent category.

reasonstring | null

Evidence-based reason the prompt was suggested.

statussuggested | tracked | dismissed | expired

Suggestion lifecycle state.

tracked_prompt_iduuid | null

Prompt created when this suggestion was tracked.

created_atdatetime

Suggestion creation time.

tracked_atdatetime | null

Time the suggestion became a tracked prompt.

dismissed_atdatetime | null

Time the suggestion was dismissed.

expired_atdatetime | null

Time the suggestion was automatically expired.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records requested per page.

totalinteger

Total records matching the filters.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/suggested_prompts?status=suggested&page=1&per_page=20' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "suggested_prompts": [
    {
      "id": "5c297c06-6609-4e2f-ab59-3297e10be39f",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "What are the best ways to improve brand visibility in AI answers?",
      "category": "general",
      "reason": "Diagnosis found low visibility for non-branded discovery questions.",
      "status": "suggested",
      "tracked_prompt_id": null,
      "created_at": "2026-07-31T08:00:00Z",
      "tracked_at": null,
      "dismissed_at": null,
      "expired_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5,
    "total_pages": 1
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_request | invalid_date_range | range_too_large

A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot manage this visibility scope.

404not_found

The project, location, or suggested prompt was not found.

409conflict

The requested lifecycle operation conflicts with current state.

422validation_failed | prompt_limit_reached | daily_prompt_activation_limit_reached

Input is invalid, a suggested-prompt status is unsupported, capacity is exhausted, or a bulk request exceeds 100 rows.

429rate_limit_exceeded

Too many requests were made.

POST
project/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/track

Converts one visible suggestion into an active prompt and schedules a visibility run. The operation consumes active and daily activation capacity.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
suggested_prompt_iduuid

Suggested Prompt identifier.

Required
Object

SuggestedPrompt

iduuid

Suggested prompt identifier.

topic_iduuid

Existing topic selected for the suggestion.

topic_namestring

Current name of the selected topic.

contentstring

Suggested prompt question.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt intent category.

reasonstring | null

Evidence-based reason the prompt was suggested.

statussuggested | tracked | dismissed | expired

Suggestion lifecycle state.

tracked_prompt_iduuid | null

Prompt created when this suggestion was tracked.

created_atdatetime

Suggestion creation time.

tracked_atdatetime | null

Time the suggestion became a tracked prompt.

dismissed_atdatetime | null

Time the suggestion was dismissed.

expired_atdatetime | null

Time the suggestion was automatically expired.

Response

Response envelope

project_id:uuidsuggested_prompts:SuggestedPrompt[]prompts:Prompt[]
project_iduuid

Resolved Ceyo project identifier.

suggested_promptsSuggestedPrompt[]

Suggestions transitioned to tracked.

promptsPrompt[]

Prompts created from the suggestions.

Object

Prompt

iduuid

Unique prompt identifier.

topic_iduuid

Topic that contains the prompt.

topic_namestring

Current name of the containing topic.

contentstring

Question sent to configured AI models. Maximum 20,000 characters.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Stable snake_case intent category.

city_overridestring | null

Prompt-specific city. Null means the city is inherited from the selected scope.

country_overridestring | null

Prompt-specific country. Null means the country is inherited from the selected scope; present together with country_code_override.

country_code_overridestring | null

Prompt-specific uppercase ISO 3166-1 alpha-2 country code. Null means the code is inherited; present together with country_override.

archived_atdatetime | null

Archive time. Null means the prompt is active.

created_atdatetime

Prompt creation time in ISO 8601 format.

metricsPromptMetrics | null

Visibility metrics for the requested date and model filters.

Object

PromptMetrics

primary_mentionsinteger

Responses that mentioned the primary tracked brand.

visibility_percentagenumber

Share of responses that mentioned the primary tracked brand.

visibility_trend_ppnumber | null

Percentage-point change from the preceding equal-length period.

average_positionnumber | null

Average 1-based primary-brand position when mentioned.

position_trendnumber | null

Average-position change from the preceding period.

average_position_trendnumber | null

Change in average position from the preceding comparison window.

average_sentimentnumber | null

Average primary-brand sentiment score.

sentiment_countsSentimentCounts

Response counts keyed by negative, neutral, and positive.

citationsinteger

Citation occurrences across matching responses.

competitor_mentionsRecord<string, integer>

Mention counts keyed by tracked competitor name.

Object

SentimentCounts

negativeinteger

Negative responses.

neutralinteger

Neutral responses.

positiveinteger

Positive responses.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/track' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "suggested_prompts": [
    {
      "id": "5c297c06-6609-4e2f-ab59-3297e10be39f",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "What are the best ways to improve brand visibility in AI answers?",
      "category": "general",
      "reason": "Diagnosis found low visibility for non-branded discovery questions.",
      "status": "tracked",
      "tracked_prompt_id": "4de5e484-ce6a-4e45-ad7c-bd48db2549af",
      "created_at": "2026-07-31T08:00:00Z",
      "tracked_at": "2026-07-31T10:10:00Z",
      "dismissed_at": null,
      "expired_at": null
    }
  ],
  "prompts": [
    {
      "id": "4de5e484-ce6a-4e45-ad7c-bd48db2549af",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "Which platforms help brands measure visibility in AI answers?",
      "category": "organic_search",
      "city_override": null,
      "country_override": null,
      "country_code_override": null,
      "archived_at": null,
      "created_at": "2026-07-20T08:35:00Z",
      "metrics": null
    }
  ]
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_request | invalid_date_range | range_too_large

A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot manage this visibility scope.

404not_found

The project, location, or suggested prompt was not found.

409conflict

The requested lifecycle operation conflicts with current state.

422validation_failed | prompt_limit_reached | daily_prompt_activation_limit_reached

Input is invalid, a suggested-prompt status is unsupported, capacity is exhausted, or a bulk request exceeds 100 rows.

429rate_limit_exceeded

Too many requests were made.

POST
project/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/dismiss

Dismisses one visible suggestion without creating a prompt. Dismissed content remains fingerprinted to prevent the same suggestion from reappearing.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
suggested_prompt_iduuid

Suggested Prompt identifier.

Required
Object

SuggestedPrompt

iduuid

Suggested prompt identifier.

topic_iduuid

Existing topic selected for the suggestion.

topic_namestring

Current name of the selected topic.

contentstring

Suggested prompt question.

categorygeneral | organic_search | brand_sentiment | competitor_comparison

Prompt intent category.

reasonstring | null

Evidence-based reason the prompt was suggested.

statussuggested | tracked | dismissed | expired

Suggestion lifecycle state.

tracked_prompt_iduuid | null

Prompt created when this suggestion was tracked.

created_atdatetime

Suggestion creation time.

tracked_atdatetime | null

Time the suggestion became a tracked prompt.

dismissed_atdatetime | null

Time the suggestion was dismissed.

expired_atdatetime | null

Time the suggestion was automatically expired.

Response

Response envelope

project_id:uuidsuggested_prompts:SuggestedPrompt[]
project_iduuid

Resolved Ceyo project identifier.

suggested_promptsSuggestedPrompt[]

Suggestions transitioned to dismissed.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/suggested_prompts/{suggested_prompt_id}/dismiss' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
  "suggested_prompts": [
    {
      "id": "5c297c06-6609-4e2f-ab59-3297e10be39f",
      "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
      "topic_name": "AI visibility platforms",
      "content": "What are the best ways to improve brand visibility in AI answers?",
      "category": "general",
      "reason": "Diagnosis found low visibility for non-branded discovery questions.",
      "status": "dismissed",
      "tracked_prompt_id": null,
      "created_at": "2026-07-31T08:00:00Z",
      "tracked_at": null,
      "dismissed_at": "2026-07-31T10:12:00Z",
      "expired_at": null
    }
  ]
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_request | invalid_date_range | range_too_large

A prompt filter, model, identifier, or metrics date range is invalid, or the range exceeds three months.

401invalid_api_key

Authorization is absent or invalid.

403forbidden

The API key cannot manage this visibility scope.

404not_found

The project, location, or suggested prompt was not found.

409conflict

The requested lifecycle operation conflicts with current state.

422validation_failed | prompt_limit_reached | daily_prompt_activation_limit_reached

Input is invalid, a suggested-prompt status is unsupported, capacity is exhausted, or a bulk request exceeds 100 rows.

429rate_limit_exceeded

Too many requests were made.