# Visibility workflows

Source: https://ceyo.ai/docs/signal/visibility-workflow-guides

### 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 package**

Select the visibility cadence, prompt limit, and model keys before assigning the package to a project or location.

**2\. Choose automatic or manual setup**

Set `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 scope**

Project paths start with `/projects/{project_id}`. Location paths add `/locations/{location_id}` before the visibility resource.

**4\. Grant only needed capabilities**

Use `prompts:read` and `prompts:write`, `competitors:read` and `competitors:write`, and `visibility:read` for the corresponding operations.

> **Automatic setup is asynchronous**
>
> Automatic 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 topics**

Send a name to `POST /visibility/topics`. Use the returned topic ID when creating prompts.

**Create prompts**

`POST /visibility/prompts` creates an active prompt and starts a visibility run across the package's enabled models.

**Add prompts in bulk**

`POST /visibility/prompts/bulk_create` accepts 1–100 rows atomically. One invalid row or capacity failure rejects the request.

**Pause without deleting history**

Archive the prompt to stop active monitoring. Restore it with `POST /visibility/prompts/{prompt_id}/restore`; restoring does not start a visibility run.

```curl
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 separate**
>
> `DELETE /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 competitors**

List with `GET /competitors?state=tracked` or create one with `POST /competitors`. A tracked competitor requires a domain.

**Suggested competitors**

List with `GET /competitors?state=suggested`. Track one by patching `competitor_state` to `tracked`, or dismiss it with `DELETE /competitors/{competitor_id}`.

**Suggested prompts**

Read `GET /visibility/suggested_prompts`. Use the suggestion's `/track` or `/dismiss` action after review.

**Capacity checks**

Tracking 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 results**
>
> Removing 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 result**

`GET /visibility/summary` returns primary mentions, visibility percentage, average position, and citation count.

**Competitor comparison**

`GET /visibility/competitors` compares the primary entity with tracked competitors. Add `/timeseries` for dated mention and position series.

**Model trends**

`GET /visibility/model-trends` returns daily and range-level primary-brand visibility by model, plus an aggregate.

**Filter consistently**

Use `start`, `end`, `models`, `topic_ids`, or `prompt_id`. The default window is seven days and the maximum is three months.

```curl
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 values**
>
> Visibility 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 responses**

`GET /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 prompt**

`GET /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 scope**

`GET /citations` can group results by page or domain and supports topic, model, search, and domain filters.

**Plot citation activity**

`GET /citations/timeseries` returns daily totals, per-model frequencies, and top citations.

```curl
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 filters**
>
> Response 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.