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

Site Audit

Read current website health, pages, categories, and findings for a project or location. Audit execution is scheduled by Signal; the public API does not start audits manually.

API scopeThese endpoints are available at both scopes.
Choose the resource whose data you want to manage.Learn about scopes →

Your selection updates every endpoint path, path parameter, and example on this page.

Site Audit data belongs to the selected project or location. A project audit is not an automatic roll-up of its locations; select Location scope to inspect a specific local website.
GET
project/projects/{project_id}/site_audit

Returns the current score state, page and finding totals, blocking details, and latest audit status.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Response

Response envelope

project_id:uuidsite_audit:SiteAuditOverview
project_iduuid

Resolved project identifier.

site_auditSiteAuditOverview

Current Site Audit state and totals.

Object

SiteAuditOverview

score_resultobject

Current, refreshing, or unavailable score state.

blocking_detailsobject | null

Public crawler-blocking diagnostics.

pagesobject

Inventory and latest audit-status counts.

findingsobject

Open finding counts by severity and category.

latest_stepobject | null

Latest scheduled Site Audit step and timing.

last_page_audited_atdatetime | null

Latest page audit completion time.

Object

ScoreResult

statecurrent | refreshing | unavailable

Availability state for the score.

currentboolean

Whether the score represents the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

reasonstring | null

Reason a current score is unavailable, for example unreadable when the site returned no readable pages.

blocking_auditobject | null

Audit currently preventing a current score.

scoreScore | null

Latest available scope or page score.

Object

Score

overall_scorenumber

Overall score from 0 to 100. Broken pages score 0, and a critical finding caps the score at 40.

technical_scorenumber

Technical pillar score. 0 when the pillar was not measured.

content_scorenumber

Content pillar score. 0 when the pillar was not measured.

category_scoresobject

Scores keyed by normalized category. A category is null when it could not be measured, for example security without response headers, performance without speed data, content categories on non-HTML pages, or a category only broken pages reached.

score_capobject | null

Present when a critical finding capped the score: max, codes[], reasons[].

pages_scoredinteger | null

Pages included in the score.

pages_failedinteger | null

Scored pages that were broken and scored 0.

provisionalboolean

True when too few pages were audited for the score to be stable.

confidencenumber

Share of selected pages that were audited.

coveragenumber

Audited page coverage when available.

issue_countsobject

Finding counts represented by the score.

deltasobject

Changes from the previous score.

score_versionstring

Scoring version, currently "8". Scores from different versions are not directly comparable.

check_versionstring

Site Audit check-set version.

scored_atdatetime

Time the score was calculated.

Object

BlockingAudit

statusstring

Blocking audit status.

pagespeed_statusstring | null

PageSpeed collection status.

error_codestring | null

Stable audit failure code, for example site_unreadable when no page could be read.

completed_atdatetime | null

Audit completion time.

created_atdatetime

Audit creation time.

Object

BlockingDetails

codestring | null

Finding code, for example audit_request_challenged when only the direct request was blocked and the audit still completed.

providerstring

Detected blocking provider.

titlestring

Public blocking summary.

descriptionstring

Public explanation of the block.

recommendationstring

Recommended remediation.

http_statusinteger | null

Observed HTTP status.

diagnosticobject | null

Sanitized provider diagnostic.

allowlist_ipsstring[]

Signal crawler IPs to allow.

affected_urlURL | null

Sanitized blocked URL.

last_seen_atdatetime | null

Most recent blocking observation.

Object

OverviewPages

totalinteger

All known pages.

activeinteger

Pages in the active inventory.

removedinteger

Pages removed from the active inventory.

by_discovery_sourceobject

Active page counts keyed by discovery source.

latest_audit_statusesobject

Latest page-run counts keyed by status.

Object

FindingSummary

totalinteger

Total visible findings.

openinteger

Open visible findings.

by_statusobject

Counts keyed by finding status.

open_by_severityobject

Open counts keyed by severity.

open_by_categoryobject

Open counts keyed by normalized category.

open_issuesinteger

Distinct open issues (one per check code).

open_issues_by_severityobject

Distinct open issues keyed by severity.

Object

LatestStep

statusstring

Scheduled Site Audit step status.

started_atdatetime | null

Step start time.

completed_atdatetime | null

Step completion time.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "site_audit": {
    "score_result": {
      "state": "current",
      "current": true,
      "refreshing": false,
      "reason": null,
      "blocking_audit": null,
      "score": {
        "overall_score": 86.4,
        "technical_score": 90.2,
        "content_score": 83.3,
        "category_scores": {
          "performance": 78.0,
          "crawlability": 94.0,
          "security": 96.0,
          "structured_data": 82.0,
          "content_quality": 81.0,
          "content_structure": 88.0,
          "meta_onpage": 91.0,
          "aeo_readiness": 76.0
        },
        "score_cap": null,
        "confidence": 0.96,
        "coverage": 1.0,
        "pages_scored": 42,
        "pages_failed": 0,
        "provisional": false,
        "issue_counts": {"critical": 0, "high": 2, "medium": 5},
        "deltas": {"overall_score": 2.1},
        "score_version": "8",
        "check_version": "site-audit-checks-4",
        "scored_at": "2026-08-09T09:30:00Z"
      }
    },
    "blocking_details": null,
    "pages": {
      "total": 42,
      "active": 42,
      "removed": 0,
      "by_discovery_source": {"sitemap": 42},
      "latest_audit_statuses": {"succeeded": 42}
    },
    "findings": {
      "total": 18,
      "open": 7,
      "by_status": {"open": 7, "resolved": 11},
      "open_by_severity": {"high": 2, "medium": 5},
      "open_issues": 4,
      "open_issues_by_severity": {"high": 1, "medium": 3},
      "open_by_category": {"meta_onpage": 3, "crawlability": 4}
    },
    "latest_step": {
      "status": "succeeded",
      "started_at": "2026-08-09T09:25:00Z",
      "completed_at": "2026-08-09T09:31:00Z"
    },
    "last_page_audited_at": "2026-08-09T09:30:45Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/site_audit/categories

Returns current category scores and the metrics shown in the Site Audit technical and content views.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Response

Response body

project_id:uuidstate:stringcurrent:booleanrefreshing:booleancategories:object | nullcategory_metrics:objectblocking_audit:object | nullscore_version:string | nullcheck_version:string | null
project_iduuid

Resolved project identifier.

statestring

Current score state.

currentboolean

Whether scores represent the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

categoriesobject | null

Score keyed by Site Audit category. A category is null when it could not be measured.

category_metricsobject

Metrics and sections keyed by category.

blocking_auditobject | null

Audit currently refreshing or blocking scoring.

score_versionstring | null

Scoring version, currently "8". Scores from different versions are not directly comparable.

check_versionstring | null

Site Audit check-set version.

Object

CategoryMetrics

generated_atdatetime | null

Metric generation time.

total_pagesinteger

Pages represented by these metrics.

categoriesobject<string, CategoryMetric>

Metrics keyed by normalized Site Audit category.

Object

CategoryMetric

scorenumber | null

Category score.

issue_countinteger

Findings in this category.

affected_pagesinteger

Distinct affected pages.

severity_countsobject

Finding counts keyed by severity.

metricsMetric[]

Category-specific headline metrics.

sectionsobject[]

Category-specific detail sections.

Object

Metric

keystring

Stable metric key.

labelstring

Display label.

valuenumber | string | null

Metric value.

suffixstring | null

Optional display suffix.

tonestring | null

Optional display tone.

Object

BlockingAudit

statusstring

Blocking audit status.

pagespeed_statusstring | null

PageSpeed collection status.

error_codestring | null

Stable audit failure code, for example site_unreadable when no page could be read.

completed_atdatetime | null

Audit completion time.

created_atdatetime

Audit creation time.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/categories' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "state": "current",
  "current": true,
  "refreshing": false,
  "categories": {"crawlability": 94.0, "content_quality": 81.0},
  "category_metrics": {
    "generated_at": "2026-08-09T09:30:00Z",
    "total_pages": 42,
    "categories": {
      "crawlability": {
        "score": 94.0,
        "issue_count": 4,
        "affected_pages": 3,
        "severity_counts": {"medium": 4},
        "metrics": [],
        "sections": []
      }
    }
  },
  "score_version": "8",
  "check_version": "site-audit-checks-4",
  "blocking_audit": null
}
Example scopeCategory maps can contain every supported category; the example shows representative entries to keep it readable.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/site_audit/pages

Lists the current page inventory with score, latest run, and finding summaries.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Records per page. Maximum: 50.

OptionalDefault: 20
qstring

URL or path search. Maximum: 200 characters.

Optional
statusactive | removed

Inventory status filter.

OptionalDefault: active
discovery_sourceseed | sitemap | crawl | provider | manual | redirect

Discovery source filter.

Optional
audit_statuspending | running | succeeded | failed

Latest page audit status.

Optional
sortlast_audited_at | url | score | issues

Sort field.

OptionalDefault: last_audited_at
directionasc | desc

Sort direction.

OptionalDefault: desc
Response

Response envelope

project_id:uuidpages:Page[]pagination:Pagination
project_iduuid

Resolved project identifier.

pagesPage[]

Matching audited pages.

paginationPagination

Offset pagination metadata.

Object

Page

iduuid

Audited page identifier.

urlURL

Sanitized page URL.

normalized_urlURL

Canonical URL used to identify the page.

hoststring

Page hostname.

pathstring

Page path.

statusactive | removed

Inventory status.

discovery_sourceseed | sitemap | crawl | provider | manual | redirect

How Signal discovered the page.

first_discovered_atdatetime

Time Signal first discovered the page.

last_discovered_atdatetime

Most recent discovery time.

last_audited_atdatetime | null

Most recent completed audit time.

latest_runobject | null

Latest page audit status and public fetch details.

score_resultobject

Current page score state and score.

open_findingsobject

Open finding total and severity counts.

Object

LatestRun

statuspending | running | succeeded | failed

Page audit status.

http_statusinteger | null

Observed HTTP status.

final_urlURL | null

Sanitized final URL after redirects.

fetch_msinteger | null

Origin fetch duration in milliseconds.

error_codestring | null

Stable failure code.

error_messagestring | null

Safe public failure message.

completed_atdatetime | null

Completion time.

Object

ScoreResult

statecurrent | refreshing | unavailable

Availability state for the score.

currentboolean

Whether the score represents the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

reasonstring | null

Reason a current score is unavailable, for example unreadable when the site returned no readable pages.

blocking_auditobject | null

Audit currently preventing a current score.

scoreScore | null

Latest available scope or page score.

Object

PageScore

overall_scorenumber

Page score from 0 to 100.

category_scoresobject

Page scores keyed by normalized category. A category is null when it could not be measured, for example security without response headers, performance without speed data, or content categories on non-HTML pages.

issue_countsobject

Page finding counts represented by the score.

Object

OpenFindings

totalinteger

Total open customer-visible findings.

by_severityobject

Open counts keyed by severity.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records returned per page.

totalinteger

Total matching records.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/pages?page=1&per_page=20' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "pages": [{
    "id": "eb67fc48-e109-42cc-bbeb-1b2b8042bd14",
    "url": "https://example.com/",
    "normalized_url": "https://example.com/",
    "host": "example.com",
    "path": "/",
    "status": "active",
    "discovery_source": "sitemap",
    "first_discovered_at": "2026-07-01T10:00:00Z",
    "last_discovered_at": "2026-08-09T09:20:00Z",
    "last_audited_at": "2026-08-09T09:30:00Z",
    "latest_run": {
      "status": "succeeded",
      "http_status": 200,
      "final_url": "https://example.com/",
      "fetch_ms": 218,
      "error_code": null,
      "error_message": null,
      "completed_at": "2026-08-09T09:30:00Z"
    },
    "score_result": {
      "state": "current",
      "current": true,
      "refreshing": false,
      "reason": null,
      "blocking_audit": null,
      "score": {
        "overall_score": 92.0,
        "category_scores": {"crawlability": 96.0, "meta_onpage": 88.0},
        "issue_counts": {"medium": 1}
      }
    },
    "open_findings": {"total": 1, "by_severity": {"medium": 1}}
  }],
  "pagination": {"page": 1, "per_page": 20, "total": 42, "total_pages": 3}
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_filter

A filter value is not supported.

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422validation_failed | visibility_unavailable

The input is invalid or project-level visibility is unavailable.

429rate_limit_exceeded

Too many requests were made.

GET

Get Site Audit page

project/projects/{project_id}/site_audit/pages/{page_id}

Returns one page with its current score, latest audit, and open finding counts.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
page_iduuid

Site Audit page identifier.

Required
Response

Response envelope

project_id:uuidpage:Page
project_iduuid

Resolved project identifier.

pagePage

Requested audited page.

Object

Page

iduuid

Audited page identifier.

urlURL

Sanitized page URL.

normalized_urlURL

Canonical URL used to identify the page.

hoststring

Page hostname.

pathstring

Page path.

statusactive | removed

Inventory status.

discovery_sourceseed | sitemap | crawl | provider | manual | redirect

How Signal discovered the page.

first_discovered_atdatetime

Time Signal first discovered the page.

last_discovered_atdatetime

Most recent discovery time.

last_audited_atdatetime | null

Most recent completed audit time.

latest_runobject | null

Latest page audit status and public fetch details.

score_resultobject

Current page score state and score.

open_findingsobject

Open finding total and severity counts.

Object

LatestRun

statuspending | running | succeeded | failed

Page audit status.

http_statusinteger | null

Observed HTTP status.

final_urlURL | null

Sanitized final URL after redirects.

fetch_msinteger | null

Origin fetch duration in milliseconds.

error_codestring | null

Stable failure code.

error_messagestring | null

Safe public failure message.

completed_atdatetime | null

Completion time.

Object

ScoreResult

statecurrent | refreshing | unavailable

Availability state for the score.

currentboolean

Whether the score represents the latest completed audit.

refreshingboolean

Whether a newer scheduled audit is processing.

reasonstring | null

Reason a current score is unavailable, for example unreadable when the site returned no readable pages.

blocking_auditobject | null

Audit currently preventing a current score.

scoreScore | null

Latest available scope or page score.

Object

PageScore

overall_scorenumber

Page score from 0 to 100.

category_scoresobject

Page scores keyed by normalized category. A category is null when it could not be measured, for example security without response headers, performance without speed data, or content categories on non-HTML pages.

issue_countsobject

Page finding counts represented by the score.

Object

OpenFindings

totalinteger

Total open customer-visible findings.

by_severityobject

Open counts keyed by severity.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/pages/{page_id}' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "page": {
    "id": "eb67fc48-e109-42cc-bbeb-1b2b8042bd14",
    "url": "https://example.com/",
    "normalized_url": "https://example.com/",
    "host": "example.com",
    "path": "/",
    "status": "active",
    "discovery_source": "sitemap",
    "first_discovered_at": "2026-07-01T10:00:00Z",
    "last_discovered_at": "2026-08-09T09:20:00Z",
    "last_audited_at": "2026-08-09T09:30:00Z",
    "latest_run": {
      "status": "succeeded",
      "http_status": 200,
      "final_url": "https://example.com/",
      "fetch_ms": 218,
      "error_code": null,
      "error_message": null,
      "completed_at": "2026-08-09T09:30:00Z"
    },
    "score_result": {
      "state": "current",
      "current": true,
      "refreshing": false,
      "reason": null,
      "blocking_audit": null,
      "score": {
        "overall_score": 92.0,
        "category_scores": {"crawlability": 96.0, "meta_onpage": 88.0},
        "issue_counts": {"medium": 1}
      }
    },
    "open_findings": {"total": 1, "by_severity": {"medium": 1}}
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/site_audit/findings

Lists individual findings or groups open findings by check when grouped=true.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Query parameters

pageinteger

1-based page number.

OptionalDefault: 1
per_pageinteger

Records per page. Maximum: 50.

OptionalDefault: 20
groupedboolean

Return open findings grouped by check. Grouped responses are not paginated.

OptionalDefault: false
limitinteger

Grouped result limit from 1 to 20.

OptionalDefault: 20
qstring

Finding text search. Maximum: 200 characters.

Optional
statusopen | resolved | ignored | all

Status filter for individual findings.

OptionalDefault: open
severitycritical | high | medium | low | info

Severity filter.

Optional
categorySiteAuditCategory

performance, crawlability, security, structured_data, content_quality, content_structure, meta_onpage, or aeo_readiness. HTTP status and content-type findings are under crawlability.

Optional
areatechnical | content

Finding area filter.

Optional
page_iduuid

Return findings for one audited page.

Optional
Response

Individual response envelope

project_id:uuidgrouped:falsefindings:Finding[]summary:objectpagination:Pagination
project_iduuid

Resolved project identifier.

groupedfalse

Indicates an individual finding response.

findingsFinding[]

Paginated matching findings.

summaryobject

Scope-wide finding totals and status counts.

paginationPagination

Offset pagination metadata.

Response

Grouped response envelope

project_id:uuidgrouped:truetruncated:booleangroups:FindingGroup[]
project_iduuid

Resolved project identifier.

groupedtrue

Indicates a grouped response.

truncatedboolean

Whether the grouped result was bounded before all matches were represented.

groupsFindingGroup[]

Up to 20 groups: current issues before stale ones, then by impact_points, then severity.

Object

Finding

iduuid

Finding identifier.

codestring

Site Audit check code. New codes may be added; retired codes stop being reported and their open findings resolve.

categorystring

Normalized technical or content category.

severitycritical | high | medium | low | info

Current severity. A critical finding caps the overall score at 40; info findings do not affect the score.

statusopen | resolved | ignored

Current finding status.

target_kindstring

Type of resource affected by the finding.

targetstring | null

Affected page or target.

titlestring

Finding title.

descriptionstring | null

Observed condition.

recommendationstring | null

Recommended remediation.

remediationRemediation | null

Copy-ready fix when one is available.

occurrencesinteger

Number of times the finding has been observed.

first_seen_atdatetime

Time the finding was first observed.

last_seen_atdatetime

Most recent observation time.

resolved_atdatetime | null

Time the finding resolved.

Object

Remediation

fieldstring

Page field to change.

beforestring | null

Current value.

afterstring

Proposed value.

snippetstring

Copy-ready HTML or JSON-LD.

rationalestring | null

Reason for the proposed change.

Object

FindingGroup

codestring

Shared Site Audit check code.

titlestring

Group title. Generic when the affected pages have different details.

descriptionstring | null

Shared description, or null when the affected pages differ.

why_it_mattersstring | null

Short explanation of why the issue matters.

recommendationstring | null

Representative recommendation.

severitycritical | high | medium | low | info

Highest severity in the group.

impact_pointsnumber | null

Estimated score points gained by fixing the issue.

templateboolean

Whether the issue appears on most audited pages, which usually means a shared template.

staleboolean

Whether the issue was not re-checked in the latest audit.

categorySiteAuditCategory

Normalized category.

pillartechnical | content

Top-level Site Audit area.

occurrencesinteger

Occurrences represented by the bounded result set.

affected_pagesinteger

Distinct affected pages represented by the result set. Site-wide findings are not counted as pages.

findings_countinteger

Matching findings represented by the result set.

findings_truncatedboolean

Whether the findings array is incomplete.

findingsFinding[]

Up to 50 matching findings.

Object

FindingSummary

totalinteger

Total visible findings.

openinteger

Open visible findings.

by_statusobject

Counts keyed by finding status.

open_by_severityobject

Open counts keyed by severity.

open_by_categoryobject

Open counts keyed by normalized category.

open_issuesinteger

Distinct open issues (one per check code).

open_issues_by_severityobject

Distinct open issues keyed by severity.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Records returned per page.

totalinteger

Total matching records.

total_pagesinteger

Total available pages.

Request and response

Example requestcURL
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}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "grouped": true,
  "truncated": false,
  "groups": [{
    "code": "missing_title",
    "title": "Missing title",
    "description": "The page does not define a title.",
    "why_it_matters": "The title is often the first thing search and AI tools show for a page.",
    "recommendation": "Add a concise, descriptive title.",
    "severity": "high",
    "impact_points": 2.4,
    "template": false,
    "stale": false,
    "category": "meta_onpage",
    "pillar": "content",
    "occurrences": 1,
    "affected_pages": 1,
    "findings_count": 1,
    "findings_truncated": false,
    "findings": [{
      "id": "3c77a8fa-d0ea-49f6-a49e-a6ae23e33ef3",
      "code": "missing_title",
      "category": "meta_onpage",
      "severity": "high",
      "status": "open",
      "target_kind": "page",
      "target": "https://example.com/about",
      "title": "Missing title",
      "description": "The page does not define a title.",
      "recommendation": "Add a concise, descriptive title.",
      "occurrences": 1,
      "first_seen_at": "2026-08-01T10:00:00Z",
      "last_seen_at": "2026-08-09T09:30:00Z",
      "resolved_at": null
    }]
  }]
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_filter

A filter value is not supported.

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422validation_failed | visibility_unavailable

The input is invalid or project-level visibility is unavailable.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/site_audit/findings/{finding_id}

Returns one finding and up to 100 recent observations.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
finding_iduuid

Site Audit finding identifier.

Required
Response

Response envelope

project_id:uuidfinding:FindingDetailobservations:Observation[]
project_iduuid

Resolved project identifier.

findingFindingDetail

Requested finding.

observationsObservation[]

Up to 100 observations, newest first.

Object

FindingDetail

iduuid

Finding identifier.

codestring

Site Audit check code. New codes may be added; retired codes stop being reported and their open findings resolve.

categorystring

Normalized technical or content category.

severitycritical | high | medium | low | info

Current severity. A critical finding caps the overall score at 40; info findings do not affect the score.

statusopen | resolved | ignored

Current finding status.

target_kindstring

Type of resource affected by the finding.

targetstring | null

Affected page or target.

titlestring

Finding title.

descriptionstring | null

Observed condition.

recommendationstring | null

Recommended remediation.

remediationRemediation | null

Copy-ready fix when one is available.

occurrencesinteger

Number of times the finding has been observed.

first_seen_atdatetime

Time the finding was first observed.

last_seen_atdatetime

Most recent observation time.

resolved_atdatetime | null

Time the finding resolved.

evidenceobject

Sanitized evidence supporting the finding.

Object

Remediation

fieldstring

Page field to change.

beforestring | null

Current value.

afterstring

Proposed value.

snippetstring

Copy-ready HTML or JSON-LD.

rationalestring | null

Reason for the proposed change.

Object

Observation

outcomedetected | resolved

Finding state during this observation.

severitycritical | high | medium | low | info

Observed severity.

evidenceobject

Sanitized evidence captured during this observation.

observed_atdatetime

Observation time.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/findings/{finding_id}' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "finding": {
    "id": "3c77a8fa-d0ea-49f6-a49e-a6ae23e33ef3",
    "code": "missing_title",
    "category": "meta_onpage",
    "severity": "high",
    "status": "open",
    "target_kind": "page",
    "target": "https://example.com/about",
    "title": "Missing title",
    "description": "The page does not define a title.",
    "recommendation": "Add a concise, descriptive title.",
    "remediation": {
      "field": "title",
      "before": null,
      "after": "About Acme",
      "snippet": "<title>About Acme</title>",
      "rationale": "Describes the page."
    },
    "evidence": {},
    "occurrences": 2,
    "first_seen_at": "2026-08-01T10:00:00Z",
    "last_seen_at": "2026-08-09T09:30:00Z",
    "resolved_at": null
  },
  "observations": []
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

GET
project/projects/{project_id}/site_audit/settings

Returns sitemap and crawl-discovery settings.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Response

Response envelope

project_id:uuidsettings:SiteAuditSettings
project_iduuid

Resolved project identifier.

settingsSiteAuditSettings

Current discovery settings.

Object

SiteAuditSettings

sitemap_urlsURL[]

Up to 20 sitemap URLs on the audited website host.

crawl_include_patternsstring[]

Path patterns included during crawl discovery.

crawl_exclude_patternsstring[]

Path patterns excluded during crawl discovery.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/projects/{project_id}/site_audit/settings' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}"
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "settings": {
    "sitemap_urls": ["https://example.com/sitemap.xml"],
    "crawl_include_patterns": ["/docs/*"],
    "crawl_exclude_patterns": ["/private/*"]
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable

The key lacks access or Site Audit is disabled.

404not_found

The scope or requested Site Audit resource was not found.

422visibility_unavailable

Project-level visibility is unavailable for this project.

429rate_limit_exceeded

Too many requests were made.

PATCH
project/projects/{project_id}/site_audit/settings

Updates sitemap and crawl patterns without starting an audit or inventory synchronization.

Parameters

Path parameters

project_idproject UUID | project external ID

Project identifier.

Required
PATCH semanticsOmitted fields remain unchanged. Send an empty array to clear a setting. Sitemap URLs are limited to 20; each crawl-pattern array is limited to 50 strings, with at most 500 characters per string.
Parameters

JSON body

sitemap_urlsURL[]

Up to 20 sitemap URLs on the audited website host.

Optional
crawl_include_patternsstring[]

Path patterns included during crawl discovery.

Optional
crawl_exclude_patternsstring[]

Path patterns excluded during crawl discovery.

Optional
Response

Response envelope

project_id:uuidsettings:SiteAuditSettings
project_iduuid

Resolved project identifier.

settingsSiteAuditSettings

Updated discovery settings.

Object

SiteAuditSettings

sitemap_urlsURL[]

Up to 20 sitemap URLs on the audited website host.

crawl_include_patternsstring[]

Path patterns included during crawl discovery.

crawl_exclude_patternsstring[]

Path patterns excluded during crawl discovery.

Request and response

Example requestcURL
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/*"]}'
Example responseJSON
{
  "project_id": "7c51e5f2-0bad-4e09-82de-fc876c81f531",
  "settings": {
    "sitemap_urls": ["https://example.com/sitemap.xml"],
    "crawl_include_patterns": ["/docs/*"],
    "crawl_exclude_patterns": ["/private/*"]
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | site_audit_unavailable | superadmin_managed

The key lacks access, Site Audit is disabled, or writes are centrally managed.

404not_found

The scope or requested Site Audit resource was not found.

422validation_failed | visibility_unavailable

The input is invalid or project-level visibility is unavailable.

429rate_limit_exceeded

Too many requests were made.