Optimization workflows

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

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

Monitor Site Audit health

Use site_audit:read to read the current scheduled audit results for either a project or a location.

1. Read the current overviewStart with /site_audit for score state, page totals, open finding counts, crawler blocking details, and refresh status.

2. Inspect categories and pagesUse /categories for technical and content metrics, then /pages to identify affected URLs.

3. Group findings for remediationRequest /findings?grouped=true to group open findings by check, or use the normal paginated response for individual page-level evidence.

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

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/findings?grouped=true&severity=high' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"

Audits are scheduledThe public API reads scheduled audit results. It does not provide a manual audit or synchronization endpoint.

Configure Site Audit discovery

Use site_audit:read to fetch the current settings and site_audit:write to change sitemap or crawl discovery settings. Sitemap URLs must use the website host configured for the project or location.

Read before writingFetch /site_audit/settings, change only the fields you manage, and send those fields with PATCH.

Use scoped patternsInclude patterns narrow crawl discovery; exclude patterns remove paths such as private, account, or generated pages.

curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/settings' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"sitemap_urls":["https://example.com/sitemap.xml"],"crawl_exclude_patterns":["/private/*"]}'

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.

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 --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.

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.

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

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.

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 --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.