SEO Audit API | LovableHTML Docs

Trigger on-demand SEO audits for your domains. The crawler discovers pages, checks for SEO issues, and reports back. Only one audit can run per domain at a time.

POST/api/seo-spider/runs

Start a new SEO audit run for a domain. The crawler will discover and analyze pages based on the selected mode.

Request Body

Parameter	Type	Description
`domain`required	string	Domain to audit (e.g., "your-app.com").
`urls`required	string[]	Seed URLs to crawl (min 1, must be valid URLs). All URLs must belong to the target domain. In follow mode, typically just the homepage.
`mode`required	"follow" \| "selected" \| "sitemap"	follow — spider from seed URLs following links. selected — only audit the specified URLs. sitemap — discover URLs from the domain's sitemap.
`allowSampling`	boolean	Enable URL pattern sampling on the crawler. Default: true.
`newPagesOnly`	boolean	Only audit new or updated pages since the last completed run (sitemap mode). Default: false.
`sitemapUrl`	string (URL)	Custom sitemap URL override. Falls back to the domain's configured sitemap if omitted.

Response Body

json

CopyDownload

{
  "ok": true,
  "runId": "a1b2c3d4-e5f6-...",
  "status": "running"
}

Response Codes

200

Success — Audit started. Returns runId and status: "running".

400

Bad Request — Validation failed: invalid_urls, no_sitemap, or schema error.

401

Unauthorized — Missing or invalid API key / session.

403

Forbidden — domain_not_owned, no_seo_spider_access, on_demand_limit_reached, or max_pages_per_month_limit_reached.

409

Conflict — run_already_active. An audit is already running for this domain. Response includes the active runId.

422

Unprocessable — no_new_pages. No new or updated pages found in sitemap since last audit (when newPagesOnly: true).

Example

javascript

CopyDownload

const response = await fetch(
  'https://lovablehtml.com/api/seo-spider/runs',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-lovablehtml-api-key': '<API_KEY>'
    },
    body: JSON.stringify({
      domain: 'your-app.com',
      urls: ['https://your-app.com'],
      mode: 'follow',
      allowSampling: true
    })
  }
);

const result = await response.json();
// { "ok": true, "runId": "a1b2c3d4-e5f6-...", "status": "running" }

bash

CopyDownload

curl -X POST \
  "https://lovablehtml.com/api/seo-spider/runs" \
  -H "Content-Type: application/json" \
  -H "x-lovablehtml-api-key: <API_KEY>" \
  -d '{
    "domain": "your-app.com",
    "urls": ["https://your-app.com"],
    "mode": "follow",
    "allowSampling": true
  }'

Limits: Audit access and page-per-run limits depend on your plan. Only one audit can run per domain at a time. Stale runs are automatically expired (15 min queue timeout, 90 min heartbeat timeout).