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

Visibility workflows

Configure what Signal monitors, review the resulting measurements, and inspect the underlying responses and citations.

Set up visibility tracking

Decide whether visibility belongs to a standard project or to an individual location. A locations-only project is a container and does not have project-level visibility.

1. Configure the packageSelect the visibility cadence, prompt limit, and model keys before assigning the package to a project or location.
2. Choose automatic or manual setupSet start: true when creating the resource to queue automatic onboarding. Use start: false when you will create topics, prompts, and competitors through the API.
3. Use the correct scopeProject paths start with /projects/{project_id}. Location paths add /locations/{location_id} before the visibility resource.
4. Grant only needed capabilitiesUse prompts:read and prompts:write, competitors:read and competitors:write, and visibility:read for the corresponding operations.
Automatic setup is asynchronousAutomatic onboarding creates topics, active prompts, and tracked competitors, then dispatches an initial visibility run. Do not assume the results are present when the create-resource response returns.

Manage topics and prompts

Create a durable topic first, then add the questions you want to monitor. Each prompt belongs to one topic in the same visibility scope.

Create topicsSend a name to POST /visibility/topics. Use the returned topic ID when creating prompts.
Create promptsPOST /visibility/prompts creates an active prompt and starts a visibility run across the package's enabled models.
Add prompts in bulkPOST /visibility/prompts/bulk_create accepts 1–100 rows atomically. One invalid row or capacity failure rejects the request.
Pause without deleting historyArchive the prompt to stop active monitoring. Restore it with POST /visibility/prompts/{prompt_id}/restore; restoring does not start a visibility run.
Create a project promptcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/prompts' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "topic_id": "ab20526b-6bb2-436c-8c93-5bf77ea43848",
    "content": "Which platforms help measure visibility in AI answers?",
    "category": "general"
  }'
Permanent deletion is separateDELETE /visibility/prompts/{prompt_id}/permanent starts irreversible background deletion. Prefer archive when the prompt may be needed again.

Manage competitors and suggestions

Keep tracked competitors separate from candidates. Prompt suggestions also remain separate from active prompts until you explicitly track them.

Tracked competitorsList with GET /competitors?state=tracked or create one with POST /competitors. A tracked competitor requires a domain.
Suggested competitorsList with GET /competitors?state=suggested. Track one by patching competitor_state to tracked, or dismiss it with DELETE /competitors/{competitor_id}.
Suggested promptsRead GET /visibility/suggested_prompts. Use the suggestion's /track or /dismiss action after review.
Capacity checksTracking a competitor requires an available tracked slot. Tracking a suggested prompt consumes active and daily prompt capacity and starts a visibility run.
Removal preserves stored resultsRemoving a competitor is a soft dismissal. Its stored visibility evidence remains available, and creating the same normalized domain or case-insensitive name later can reactivate it.

Read visibility results

Start with the summary, then use competitor and model endpoints when you need a breakdown. All reads require visibility:read.

Overall resultGET /visibility/summary returns primary mentions, visibility percentage, average position, and citation count.
Competitor comparisonGET /visibility/competitors compares the primary entity with tracked competitors. Add /timeseries for dated mention and position series.
Model trendsGET /visibility/model-trends returns daily and range-level primary-brand visibility by model, plus an aggregate.
Filter consistentlyUse start, end, models, topic_ids, or prompt_id. The default window is seven days and the maximum is three months.
Read project visibilitycURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/visibility/summary?start=2026-07-24&end=2026-07-30&models=chatgpt,perplexity' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Read percentages as 0–100 valuesVisibility is the share of matching responses that mention the primary entity. Average position uses only primary mentions with a detected position; citation totals count occurrences.

Work with responses and citations

Use response and citation endpoints to inspect the evidence behind aggregate visibility metrics.

Inspect model responsesGET /prompts/{prompt_id}/responses returns successful model responses, newest first, with brand presence, position, sentiment, entities, and a citation preview.
Get all citations for a promptGET /prompts/{prompt_id}/citations aggregates repeated citations across the selected date range. The separate responses endpoint previews at most three citations per model response.
Review citations across the scopeGET /citations can group results by page or domain and supports topic, model, search, and domain filters.
Plot citation activityGET /citations/timeseries returns daily totals, per-model frequencies, and top citations.
Inspect prompt responsescURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/prompts/{prompt_id}/responses?start=2026-07-24&end=2026-07-30' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Use the same scope and filtersResponse and citation paths sit under the selected project or location. Their date window defaults to seven days, can span up to three months, and can be narrowed with model keys.