---
title: "Assess a website"
method: POST
path: "/assessments"
tags: ["Assessments"]
---

# Assess a website

`POST /assessments`

## Request

- Base URL: `https://seogeoaeo.ai/api/v1`
- URL: `https://seogeoaeo.ai/api/v1/assessments`
- Auth: HTTP bearer

Checks a website in one call and scores SEO readiness, AEO readiness and AI access from 0 to 100, with the PageSpeed Insights bands: 90 to 100 good, 50 to 89 needs work, 0 to 49 poor. It runs the selected check groups on the URL and up to two more pages on the same site, and combines their fixes into one list ordered by priority. Each assessment is compared with the previous one of the same URL. progress.percentFixed is the share of the earlier issues that are now fixed, next to counts of fixed, still present and new issues. The default checks cost 67 credits for one page and 47 for each extra page. Each check is charged on its own and refunded if it fails. One call runs checks for 40 seconds, or as long as its slowest selected check: about two minutes for performance and three and a half for AI brand descriptions. Allow a client timeout of four minutes. When status is in_progress, continue with the same id to run the rest.

## Headers

- `Idempotency-Key` string: Reuse on retries so the same run is returned instead of charged again. A key only matches a run of the same tool and input, and only while that run is among the workspace's latest 1,000.

## Request body

- object
  - `input` AssessmentInput, required
    - `url` string, required: The website to assess, usually its home page.
    - `pages` string[]: Up to two more key pages.
    - `checks` string[]: Default: technical, onPage, schema, content. technical: Indexing, canonicals, robots, redirects and host consistency. onPage: Titles, descriptions and headings on each selected page. schema: JSON-LD validity and relevant schema types. content: Readability, answer structure, dates and authorship signals. images: Image text, dimensions and accessibility on each page. rendering: Rendered content, mobile parity and HTML size. performance: Core Web Vitals field data when available and lab diagnostics. structure: A separate crawl of up to 150 pages for links and sitemap coverage. brand: Visible brand names, organization markup and entity references. narrative: Ask three AI engines how they describe your brand. Separately priced.
    - `questions` string[]: Buyer questions to ask AI engines with the answers check.
    - `brand` string: The brand name to look for in AI answers.
  - `compareTo` string: Compare with this assessment instead of the previous one of the same URL.
  - `idempotencyKey` string: Reuse on retries so the same run is returned instead of charged again. A key only matches a run of the same tool and input, and only while that run is among the workspace's latest 1,000.
  - `maxCredits` integer: Refuse the run with max_credits_exceeded if it costs more than this.

## Response `200`

The assessment after this call.

- object
  - `assessment` Assessment, required
    - `id` string
    - `url` string
    - `reportUrl` string, uri: The report in the browser.
    - `createdAt` string, date-time
    - `status` 'in_progress' | 'finished': in_progress while checks are pending, running or failed. Continue it to run them.
    - `checks` object
      - `total` integer
      - `complete` integer
      - `incomplete` integer
      - `failed` integer
      - `waiting` integer
    - `credits` object
      - `charged` integer
      - `toFinish` integer: Price of the checks still to run.
    - `scores` object: 0 to 100 with the PageSpeed Insights bands: good 90 to 100, average 50 to 89, poor 0 to 49.
      - `overall` object: Null until a check of this kind finishes.
        - `score` integer, nullable
        - `band` 'good' | 'average' | 'poor' | 'null', nullable
      - `areas` object[]
        - `area` 'technical' | 'content' | 'aiAccess'
        - `label` string
        - `score` integer, nullable
        - `band` 'good' | 'average' | 'poor' | 'null', nullable
        - `checksScored` integer
        - `checks` integer
      - `issues` integer: One per fix and affected page or item.
      - `fixes` integer: Distinct fixes.
    - `progress` object, nullable: Change since the previous assessment of the same URL. Null for the first one.
      - `comparedWith` object
        - `id` string
        - `createdAt` string, date-time
        - `overall` object: Null until a check of this kind finishes.
          - `score` integer, nullable
          - `band` 'good' | 'average' | 'poor' | 'null', nullable
        - `issues` integer
      - `percentFixed` integer, nullable: Fixed issues as a share of the earlier issues that were checked again.
      - `fixed` integer
      - `stillPresent` integer
      - `new` integer
      - `notComparable` integer: Earlier issues whose check changed or did not finish, so they were not compared.
      - `changedChecks` integer: Checks whose tool was updated since then.
      - `newIssues` object[]
        - `id` string
        - `title` string
        - `affected` string[]
    - `improvementTips` ImprovementTips, nullable: What to change to improve the result. Null when the run failed or its result is no longer available.
      - `status` 'changes' | 'clean' | 'incomplete', required: incomplete when any part of the analysis could not run, changes when there are tips, clean when the tool checked everything and found nothing to change.
      - `summary` string, required: Plain-text checklist of every tip, ordered by priority.
      - `tips` ImprovementTip[], required
        - `id` string, required: Names one kind of change and stays the same across runs, so a fixed tip is recognized by its absence.
        - `priority` 'high' | 'medium' | 'low', required
        - `title` string, required
        - `action` string, required: The change to make.
        - `why` string, required
        - `detail` string, required: What the tool observed.
        - `affected` string[], required: URLs, headers, or items the change applies to.
        - `fixIn` 'dns' | 'external': Set when the change is made outside the site's code: in DNS, or in another service.
      - `unchecked` object[], required: Parts of the analysis that could not run. While not empty, the result cannot show that the site is clean.
        - `id` string, required
        - `title` string, required
        - `detail` string, required: What went wrong.
        - `action` string, required: What to do before trusting the result.
      - `rerunVerifies` boolean, required: True when running the tool again with the same input shows whether the changes worked. False when the tips come from the input, so the same input returns them again.
      - `verify` string, required: How to confirm the changes worked.
    - `failedChecks` object[]
      - `title` string
      - `url` string, nullable
      - `error` string, nullable
    - `aiAnswers` object, nullable: Sampled AI answers. Null when the answers check was not selected.
      - `asked` integer
      - `answered` integer
      - `named` integer
      - `cited` integer
    - `notes` string[]: Checks this call could not start, and why.
    - `next` string: What to do next.

## Other responses

- `400`: Error envelope.
- `401`: Error envelope.
- `402`: Error envelope.
- `404`: Error envelope.
- `409`: Error envelope.
- `413`: Error envelope.
- `429`: Error envelope.

---

[API](https://skmtc.dev/seogeoaeo/apis/seogeoaeo-ai-api.md) · [All operations](https://skmtc.dev/seogeoaeo/apis/seogeoaeo-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/seogeoaeo/apis/seogeoaeo-ai-api/revisions/e6f4e073e822?raw)