# An on-page SEO audit from one API call

> Run an on-page SEO audit for any URL with a single API call to inspect metadata, page speed, word count, link structure, and prioritized issues.

**You can run a complete on-page SEO audit by making a single POST request to the `seo.audit` endpoint with the target page URL.** thelastapi fetches the live page, evaluates core technical signals like load time, status codes, and headings, and returns an overall score alongside an ordered list of specific issues to fix. The entire audit completes synchronously and costs a fraction of a cent per URL.

Whether you run audits from a scheduled script, inside an AI agent workflow, or through the command line, the audit returns structured JSON ready for your app to display or act on.

## What does the on-page audit check?

Running manual audits across hundreds of URLs slows down site migrations, client reporting, and ongoing quality checks. The `seo.audit` action inspects critical technical and on-page ranking factors in one pass:

- **Metadata and title tags:** Checks whether `<title>` and meta description tags exist, whether they are empty, and evaluates their contents.
- **Heading hierarchy:** Inspects the main `<h1>` tag to verify presence and detect missing or duplicate primary headings.
- **Content density:** Calculates the total `word_count` to detect thin or placeholder content.
- **Speed and network performance:** Measures `load_time_ms` and records the HTTP `status_code`.
- **Protocol security:** Checks whether the page serves insecure plain HTTP instead of HTTPS.
- **Media optimization:** Detects images missing required `alt` attributes.
- **Link graphs:** Counts both `internal` and `external` links discovered on the page.

Every audit generates a numerical `score` and returns an array of `issues` sorted worst first, so you immediately see high-severity blockers before minor recommendations.

## How to call the audit API with curl

You can trigger an audit with standard HTTP tools. Send a JSON body containing the target `url` in the `input` object to `https://thelastapi.dev/v1/actions/seo.audit`:

```bash
curl https://thelastapi.dev/v1/actions/seo.audit \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input":{"url":"https://example.com/blog/running-shoes"}}'
```

The response includes the execution metadata, cost, and audit output:

```json
{
  "object": "action_result",
  "action": "seo.audit",
  "output": {
    "url": "https://example.com/blog/running-shoes",
    "status_code": 200,
    "title": "Best Trail Running Shoes: 2026 Field Guide",
    "description": "Compare top-rated trail running shoes by grip, cushion, and weight.",
    "h1": "Best Trail Running Shoes for Rough Terrain",
    "word_count": 1420,
    "load_time_ms": 340,
    "score": 88,
    "issues": [
      {
        "check": "image_alt",
        "severity": "medium",
        "message": "3 images on this page are missing alt text."
      }
    ],
    "links": {
      "internal": 18,
      "external": 4
    }
  },
  "cost_micro_usd": 2500,
  "run_id": "arun_01h8a9bcdef0123456789abcde",
  "console_url": "https://thelastapi.dev/web-data?action=seo.audit&run=arun_01h8a9bcdef0123456789abcde"
}
```

The `cost_micro_usd` field shows the raw execution expense—2,500 micro-USD is one quarter of a cent.

## Running audits from the CLI and Node.js

If you test pages locally or script automated jobs, you can use the command line directly:

```bash
vibiz seo audit https://example.com/pricing
```

You can also run any action via `vibiz run` with explicit JSON input:

```bash
vibiz run seo.audit --input '{"url":"https://example.com/pricing"}'
```

In your application code, import `@vibiz/app` to call the action directly using your project's environment credentials:

```ts
import { vibiz } from '@vibiz/app';

interface AuditResult {
  url: string;
  status_code: number;
  title: string;
  description: string;
  h1: string;
  word_count: number;
  load_time_ms: number;
  score: number;
  issues: Array<{
    check: string;
    severity: string;
    message: string;
  }>;
  links: {
    internal: number;
    external: number;
  };
}

async function auditLandingPage(url: string) {
  const result = await vibiz.actions.run('seo.audit', { url });
  const audit = result.output as AuditResult;

  console.log(`Page score for ${audit.url}: ${audit.score}/100`);

  if (audit.issues.length > 0) {
    console.log('Issues found:');
    for (const issue of audit.issues) {
      console.log(`- [${issue.severity}] ${issue.check}: ${issue.message}`);
    }
  }

  return audit;
}

await auditLandingPage('https://example.com/pricing');
```

If you need visual context alongside the technical audit, pair this call with our guide to [screenshot a web page with an API](https://thelastapi.dev/blog/screenshot-webpage-api). You can also extract markdown text for deeper LLM evaluation by following the tutorial to [scrape a website to markdown with one API call](https://thelastapi.dev/blog/scrape-website-to-markdown-api).

## Understanding the audit fields and common issues

The audit output gives you both high-level metadata and granular diagnostics. Here is what each property represents:

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | HTTP status received when fetching the target page (e.g., 200, 301, 404). |
| `title` | string | Extracted text from the HTML `<title>` tag. |
| `description` | string | Extracted content of the `meta[name="description"]` tag. |
| `h1` | string | Text contained inside the primary `<h1>` element. |
| `word_count` | number | Total count of body copy words, excluding boilerplate navigation. |
| `load_time_ms` | number | Time in milliseconds to request and receive the full page document. |
| `score` | number | Calculated health score (0–100) reflecting overall page compliance. |
| `issues` | array | Diagnostic objects containing `check`, `severity`, and an actionable `message`. |
| `links.internal` | number | Total number of hyperlinks pointing to the same domain. |
| `links.external` | number | Total number of outbound links pointing to external domains. |

When an issue appears, the `message` tells you exactly what to fix. For example, if a page uses insecure assets or lacks metadata, you will see checks like:
- `missing_title`: "The page is missing a title tag."
- `missing_description`: "No meta description found."
- `missing_h1`: "The page does not have an H1 heading."
- `plain_http`: "The URL is served over insecure HTTP instead of HTTPS."
- `slow_loading`: "Page response time exceeded recommended thresholds."
- `thin_content`: "The body text contains fewer words than recommended for indexing."
- `image_alt`: "Images found missing descriptive alt attributes."

## Automating audits across a site crawl

A single audit covers one URL. If you need to evaluate an entire site, combine `seo.audit` with `web.crawl`. First discover your site routes, then loop through them:

```ts
import { vibiz } from '@vibiz/app';

async function auditEntireSite(baseUrl: string) {
  // Step 1: Discover site pages
  const crawl = await vibiz.actions.run('web.crawl', {
    url: baseUrl,
    maxPages: 20,
    maxCharsPerPage: 500,
  });

  const pages = crawl.output.pages;
  console.log(`Discovered ${pages.length} pages. Starting audits...`);

  // Step 2: Audit each page sequentially
  for (const page of pages) {
    const audit = await vibiz.actions.run('seo.audit', { url: page.url });
    const output = audit.output;

    console.log(`Checked ${output.url} - Score: ${output.score}`);
    for (const issue of output.issues) {
      console.log(`  → [${issue.severity}] ${issue.message}`);
    }
  }
}

await auditEntireSite('https://example.com');
```

If you plan to optimize discovered keywords during this workflow, read our guide on fetching [keyword ideas with volume and difficulty from one call](https://thelastapi.dev/blog/keyword-ideas-api). You can also pass the audit payload into LLM agents to draft fixes directly; see how in [call Claude and Gemini from the OpenAI Node.js SDK](https://thelastapi.dev/blog/claude-gemini-openai-node-sdk).

## Audit pricing and spending limits

The `seo.audit` endpoint is billed based on raw operational cost plus a 30% margin:

| Resource | Base Cost (`cost_micro_usd`) | Typical Price After Margin |
| --- | --- | --- |
| Single Page Audit (`seo.audit`) | ~2,000 to ~3,000 | Fraction of a cent (~$0.003) |
| SERP Scraping (`seo.serp`) | ~2,000 | Fraction of a cent |
| 1,000 Keyword Volumes (`seo.keywords`) | ~60,000 | ~$0.08 |
| Keyword Ideas (`seo.keyword_ideas`) | ~10,000 to ~30,000 | $0.01 to $0.04 |
| Domain Overview (`seo.domain`) | ~10,000 to ~30,000 | $0.01 to $0.04 |

Every account has a default $5 daily spend ceiling shared across web data and AI endpoints, which the account owner can adjust at any time in Billing. If you exhaust available prepaid credits, the API returns HTTP `402 payment_required`. You can monitor past runs, inspect outputs, and check exact billing line-items at any time using `vibiz runs` or in the console under [Web data: scrape, search, SEO, ads library](https://thelastapi.dev/docs/actions).

To submit newly audited pages directly to search engines upon deploy, check out our automated indexing features in [Search](https://thelastapi.dev/docs/search).

## Next step

Run your first audit from your terminal using `vibiz seo audit <url>`, or inspect historical audit requests in the web console to start automating your technical SEO reporting.
===BODY===

## Frequently asked questions

### Does the audit API execute client-side JavaScript?

Yes, the crawler renders the page in a headless browser environment to measure real page load times and evaluate dynamically generated titles, headings, and DOM elements.

### How does the audit prioritize issues?

Issues are returned in the `issues` array ordered worst first, ranking high-severity technical blockers like missing status codes or broken protocol security above minor suggestions like image alt tags.

### Can I check historical audit runs without re-running the API call?

Yes, every run is saved; you can fetch previous audit inputs, outputs, and costs using `vibiz runs <run_id>` or via `GET /v1/actions/runs/:id`.

### What happens if an audited URL returns a 404 or 500 error?

The API returns HTTP 200 with the action result, where `status_code` in the payload reflects the target site's response (e.g., 404) and the issue list flags the failure accordingly. ===FAQ===

---

Published 2026-11-15 · https://thelastapi.dev/blog/on-page-seo-audit-api
