Optimization workflows as MarkdownUse a clean Markdown version of this page with an agent or local tooling.
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 queueList 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 contextCompare
priority, estimated_impact, effort_level, and feasibility. These fields support prioritization; they are not delivery or outcome guarantees.3. Inspect the evidenceGet 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 scopeUse 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.List high-priority active actionscURL
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}"Inspect one actioncURL
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 absentThe 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.
todoCan move to
in_progress, completed, or dismissed.in_progressCan move back to
todo, or forward to completed or dismissed. The first start time is retained.completed or dismissedCan be reopened to
todo. Reopening clears the corresponding completion or dismissal time.resolvedIs system-managed when supporting findings resolve. It cannot be selected or transitioned through the public API.
Mark an action completedcURL
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.
pendingThe action has no eligible baseline run, or is awaiting a post-completion run. Read the returned
reason instead of assuming measurement is available immediately.measuredThe 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.Read completed-action impactcURL
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 carefullyBefore-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 overviewGet
/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 completionList
/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 findingsList
/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 scanApply profile changes outside Signal, then use later scheduled scan data and finding status to assess whether the condition is still observed.
Read listing profile and latest scancURL
curl --request GET \
--url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/locations/{location_id}/listings/profile' \
--header "Authorization: Bearer ${SIGNAL_API_KEY}"List high-severity open findingscURL
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 endpointListing 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.