# Optimization workflows

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

### Optimization workflows

Turn generated recommendations and listing observations into trackable work, then read later measurements without treating them as guaranteed outcomes.

### Process recommended actions

Actions are generated from current findings. Use a key with `actions:read` to build a queue for either a project or a location.

**1\. Build the active queue**

List with `status=active` to include `todo` and `in_progress` actions. Narrow the queue by priority, type, effort, source category, topic, or search text.

**2\. Prioritize in context**

Compare `priority`, `estimated_impact`, `effort_level`, and `feasibility`. These fields support prioritization; they are not delivery or outcome guarantees.

**3\. Inspect the evidence**

Get the action before assigning work. The detail response adds supporting findings and may include a structured guide with implementation, validation, rollback, and expected-timeline guidance.

**4\. Preserve the scope**

Use the project action paths for project work. For location work, insert `/locations/{location_id}` before `/actions`; an action is available only in its own scope.

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions?status=active&priority=high&page=1' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
```

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/{action_id}' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
```

> **Generated guidance can be absent**
>
> The public response returns `guide: null` when no guide is available. Your workflow should still use the action's description, recommendation, target, topics, and findings.

### Track action status and impact

Use a key with `actions:write` to synchronize work status. Mark completion only after the implementation and its validation steps are finished, because `completed_at` anchors impact measurement.

**todo**

Can move to `in_progress`, `completed`, or `dismissed`.

**in\_progress**

Can move back to `todo`, or forward to `completed` or `dismissed`. The first start time is retained.

**completed or dismissed**

Can be reopened to `todo`. Reopening clears the corresponding completion or dismissal time.

**resolved**

Is system-managed when supporting findings resolve. It cannot be selected or transitioned through the public API.

```curl
curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/{action_id}' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"status":"completed"}'
```

Read impact with `actions:read`. The endpoint examines completed actions in the requested date window and compares eligible visibility runs immediately before and after completion.

**pending**

The action has no eligible baseline run, or is awaiting a post-completion run. Read the returned `reason` instead of assuming measurement is available immediately.

**measured**

The response includes baseline, comparison, and deltas for visibility, citations, sentiment, and average position where values are available.

**Outcome**

`improved`, `unchanged`, or `declined` is derived from the visibility change, not from every returned metric.

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/actions/impact?start_on=2026-05-01&end_on=2026-07-30' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
```

> **Interpret impact carefully**
>
> Before-and-after measurements show correlation. They do not prove that the completed action was the only cause of the observed change.

### Monitor listing health

Listings are read-only and available only for locations. A key needs `listings:read`, and scheduled analysis requires a configured Google place and a location package with listings enabled.

**1\. Read the current overview**

Get `/listings/profile` for the configured listing identity, newest retained profile, and latest scan summary. A successful response can contain null values when listing data is unavailable.

**2\. Track scan completion**

List `/listings/scans` newest first. Scan statuses are `pending`, `running`, `succeeded`, `failed`, or `skipped`; fetch one scan for its scored checks when a result is available.

**3\. Triage open findings**

List `/listings/findings?status=open`, then filter by severity, category, or search text. Findings expose the observed issue and recommendation but are not writable through the Listings API.

**4\. Confirm on a later scan**

Apply profile changes outside Signal, then use later scheduled scan data and finding status to assess whether the condition is still observed.

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/locations/{location_id}/listings/profile' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
```

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/locations/{location_id}/listings/findings?status=open&severity=high&page=1' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
```

> **No on-demand scan endpoint**
>
> Listing scans are created by scheduled analysis and cannot be started through the public Listings API. Detailed profile data is retained for 29 days; historical scores and checks remain available.