Skip to content

List SEO issues with their lifecycle

GET
/v1/sites/{id}/seo-issues
curl --request GET \
--url 'https://api.overwatch.weareheavy.dev/v1/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/seo-issues?status=open&severity=critical&limit=100' \
--header 'x-api-key: <x-api-key>'

SEO issues with a stable identity across crawls. There is one issue per rule per page, and each issue is new, open, resolved (fixed or page-gone) or reopened. Newest first, keyset-paginated: follow nextCursor until it’s null. The site’s excludePaths globs are applied after paging, so a page of results can hold fewer than limit issues.

Intended for CMS integrations. Pass url to show a document’s issues in the editor, or new=true to list what broke in the latest crawl.

Responds 404 when the SEO app is not enabled for the site.

id
required
string format: uuid

The site’s UUID.

status
string
default: open
Allowed values: open resolved all
new
boolean

true returns open issues opened, or reopened after a fix, in the latest crawl. After a starting-point (baseline) crawl, nothing is new.

changedIn
string

A run id. Returns issues opened, reopened after a fix, or resolved in that run.

url
string format: uri

An absolute page URL. It is keyed the way the crawler keys pages (www/non-www folding, the site’s stripParams dropped), so a document’s public URL matches as-is.

rule
string

A rule id from the SEO rule catalog (e.g. meta-noindex).

severity
string
Allowed values: critical serious moderate minor
limit
integer
default: 100 >= 1 <= 200
cursor
string

The opaque nextCursor from the previous page.

A page of issues.

Media typeapplication/json
object
run
required

The latest SEO-extracting run, which isNew and new=true are relative to.

object
id
required
string
issues
required
Array<object>

One SEO finding (a rule on a page) with its lifecycle across crawls.

object
id
required

Stable across crawls. Also carried by seo.indexability_lost webhooks.

string
rule
required
string
severity
required

The latest observed severity.

string
Allowed values: critical serious moderate minor
title
required
string
help
required
string
fix
required

What to change to resolve it, in editor terms.

string
pageUrl
required
string format: uri
detail
required

The latest observation’s specifics.

string | null
content
required

The latest offending value (title/description/canonical/robots text).

string | null
status
required
string
Allowed values: open resolved
isNew
required

Opened, or reopened after a fix, in the latest crawl.

boolean
firstSeenAt
required

Epoch ms.

integer
firstSeenRunId
required
string
resolvedAt
required
integer | null
resolvedRunId
required
string | null
resolution
required

fixed: the page was crawled and the rule no longer fires. page-gone: a complete crawl no longer reaches the page.

string | null
Allowed values: fixed page-gone
reopenCount
required

Times this issue came back after being fixed.

integer
nextCursor
required
string | null
Example
{
"issues": [
{
"severity": "critical",
"status": "open",
"resolution": "fixed"
}
]
}

An invalid filter, limit, cursor, or URL.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
"error": "status must be one of: open, resolved, all"
}

Missing or invalid credentials.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
"error": "invalid api key"
}

The site was not found, or the SEO app is not enabled.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
"error": "SEO is not enabled for this site"
}