SEO

Get site health

The latest technical SEO audit of the site: the score, every check with its verdict and recommendation in fix order, how much of the site the crawl covered, the change since the previous audit, and the score history.

GEThttps://api.vidrys.com/v1/projects/{project_id}/seo/site-health

Plan: Track and above
Key: read
Rate cost: 2 units
MCP tool: get_site_health

Whole-site checks — orphan pages, duplicates, broken internal links — are reported unknown when the crawl saw too little of the site to judge them, rather than invented from a partial picture.

Get site health

curl --request GET \
  --url "https://api.vidrys.com/v1/projects/{project_id}/seo/site-health" \
  --header "Authorization: Bearer $VIDRYS_API_KEY"

200 · success

{
  "audited": true,
  "score": 71.5,
  "coverage": 0.94,
  "pages_audited": 200,
  "ran_at": "2026-09-28T03:40:12+00:00",
  "crawl": {
    "completeness": 0.83,
    "completeness_floor": 0.6,
    "sitemap_url_count": 240,
    "hit_page_cap": true,
    "crawled_at": "2026-09-28T03:31:04+00:00",
    "host": "acmeinvoicing.com"
  },
  "previous_score": 67.5,
  "previous_ran_at": "2026-09-21T03:39:50+00:00",
  "score_delta": 4,
  "same_crawl_as_previous": false,
  "issue_changes": {
    "new": 2,
    "persistent": 11,
    "resolved": 5,
    "not_rechecked": 0,
    "newly_checked": 0
  },
  "checks": [
    {
      "id": "meta_description",
      "label": "Meta descriptions",
      "pillar": "on_page",
      "weight": 6,
      "score": 0.85,
      "points": 5.1,
      "status": "partial",
      "detail": "30 of 200 pages have no meta description.",
      "recommendation": "Write a 50–160 character description for each page without one.",
      "impact": "medium"
    }
  ],
  "fix_order": [
    "indexable",
    "meta_description",
    "title_quality"
  ],
  "trend": [
    {
      "ran_at": "2026-09-28T03:40:12+00:00",
      "score": 71.5,
      "coverage": 0.94,
      "pages_audited": 200,
      "issues": 41,
      "severity_counts": [
        {
          "label": "high",
          "count": 6
        },
        {
          "label": "medium",
          "count": 35
        }
      ]
    }
  ]
}

Authorization

Sent as a header on every request.

Authorizationstringrequired

A Vidrys API key, sent as Bearer vidrys_sk_…. A read key is enough. See Authentication.

Path parameters

project_idstringrequired

The project's id, from List projects.

Response · 200

application/json

auditedboolean

False until a crawl of the site has been graded. Every field below is then empty.

scorenumbernullable

Site health, 0–100.

coveragenumbernullable

Share of the audit that could be measured, 0–1.

pages_auditedinteger

Pages graded.

ran_atstringnullable

When the audit ran, ISO 8601.

crawlobjectnullable

How much of the site the graded crawl reached.

+Show child attributes

completenessnumber

Share of the site crawled, 0–1.

completeness_floornumber

Below this share the whole-site checks are reported unknown.

sitemap_url_countintegernullable

URLs in the sitemap the crawl was sized against.

hit_page_capboolean

The crawl stopped at its page budget rather than running out of links.

crawled_atstringnullable

When the crawl finished, ISO 8601.

hoststringnullable

The site graded.

previous_scorenumbernullable

The previous audit's score.

previous_ran_atstringnullable

When it ran.

score_deltanumbernullable

Points against the previous audit.

same_crawl_as_previousbooleannullable

True when the previous audit graded the same crawl: the delta is a re-grade, not a change on the site.

issue_changesobjectnullable

The issues against the previous audit, counted per check and page.

+Show child attributes

newinteger

Issues that were not there last time.

persistentinteger

Issues still there.

resolvedinteger

Issues gone from a page that was graded again.

not_recheckedinteger

Earlier issues on pages not graded this time.

newly_checkedinteger

Issues on checks the previous audit did not run.

checksobject[]

Every check with its verdict.

+Show child attributes

idstring

Check id, e.g. meta_description, broken_internal_links, core_web_vitals.

labelstring

Its name on the screen.

pillarstringnullable

The group it belongs to.

weightnumber

Points the check is worth out of 100.

scorenumbernullable

Share passed, 0–1. Null when unmeasured.

pointsnumbernullable

Points earned.

statusstring

The verdict. unknown when the check could not be measured — too little of the site crawled, or a reading that did not answer.

Values:passpartialfailunknown

detailstringnullable

What was found, in words.

recommendationstringnullable

What to do about it.

impactstringnullable

How much it matters: high, medium or low.

fix_orderstring[]

Check ids in the order worth fixing them.

trendobject[]

One point per crawl graded, oldest first.

+Show child attributes

ran_atstring

When the audit ran, ISO 8601.

scorenumbernullable

Site health then.

coveragenumbernullable

Share measured.

pages_auditedinteger

Pages graded.

issuesinteger

Issues found.

severity_countsobject[]

Issues per severity.

+Show child attributes

labelstring

Severity.

Values:criticalhighmediumlow

countinteger

How many.

Errors

403 plan_feature_unavailable	The feature is on a higher plan. Bulk exports and webhooks are Custom-only.
404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
422 invalid_request	A parameter or body field is missing or has the wrong type or value. The message names the field. Also returned when a write would pass the plan's prompt limit.
401 unauthorized	No key was sent, or the key is unknown, revoked or expired, or the member who created it has left the workspace or been deactivated.
402 plan_required	The workspace's plan doesn't include API access. It's included on every plan from Track up — Solo is the one without it.
403 workspace_not_approved	The workspace is still waiting for approval, or wasn't approved.
429 rate_limited	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header, then retry.

Every code, and what to retry, is in Errors.