Build an SEO audit.
Run it in n8n.

01 / See the result first

Run a complete example with saved data

Start with the saved-data demo workflow. It contains a real report for our SEO API comparison page and the same transformation used by the live workflow. It makes no API requests and needs no credentials.

1. Create a workflow in n8n. Open its menu and choose Import from File, then select demo-workflow.json.
2. Select Execute Workflow. The three nodes load the saved report and build the review queue.
3. Open Build review queue → Output → JSON. You should see one item with a score of 85, 10 comparison pages, and 15 entries in gaps.

{
  "targetUrl": "https://api.on-page.ai/best-seo-api",
  "keyword": "best seo api",
  "region": "US",
  "score": 85,
  "comparedPages": 10,
  "nextStep": "editorial_review"
}

Each gap includes its term, competitor prevalence, and a needs_review status. For example, “testing” appears on seven comparison pages and is missing from the target page. That gives the next step in your workflow specific evidence to use.

The workflows use built-in n8n nodes. Import and execution were verified with n8n 2.39.5, using the saved report and a local API fixture for the live workflow’s control flow.

02 / Connect once

Keep authentication in n8n’s credential store

Import live-workflow.json into a second workflow. You’ll see the scan request, a polling loop, a result request, and the review-queue builder.

1. Open Submit scan. Authentication is set to Generic Credential Type → Header Auth.
2. Create a Header Auth credential with the header name Authorization and the value Bearer YOUR_API_KEY. Get your key from the API key setup guide.
3. Select that same credential in Check status and Fetch report. All three HTTP nodes need it.

The download contains credential selectors, with no key or account-specific credential reference. Store the key in the credential form rather than the input node, code, or request URL. n8n’s HTTP credential guide explains this setup.

03 / Your first live run

Choose one page and its target keyword

Open Audit inputs and update the fields below. Use an interior page that serves the keyword you want to evaluate, such as a service page, article, or product comparison.

Select Execute Workflow to start. A new Standard scan costs 2 credits. Track job shows the job ID and request key, which you can keep for recovery.

Starting another execution with an empty resume ID creates a new scan key. To retrieve an existing scan, fill in resumeJobId first. This makes the workflow skip Submit scan.

Your live results will differ from the saved example as the page and comparison results change. The demo’s 85 score and 15 candidates are reference outputs, not required values for your own audit.

04 / The asynchronous part

Follow the job all the way to its report

A scan starts asynchronously: the POST returns a job ID before the report is ready. The workflow keeps that ID, waits, and follows the job until it can retrieve the result.

1. Submit scan calls POST /v1/scan with an Idempotency-Key. The accepted response contains job_id.
2. Wait before check pauses for 15 seconds. Check status then requests GET /v1/jobs/:id.
3. Read status counts the checks. Queued, waiting, running, and processing states return to the wait node. Failed or cancelled jobs stop with an error.
4. Fetch report runs after completion and requests GET /v1/jobs/:id/result?response_format=customer_v1.

The status response’s result field stays null. The completed report comes from the result endpoint and has fields such as entity_coverage at its top level.

The HTTP nodes include response headers and status so errors can retain their retry instructions. In n8n, the API JSON is therefore inside body. The following Code node checks the HTTP status and unwraps that body before using it.

function successfulBody(response, step) {
  const status = response.statusCode;
  if (typeof status !== "number") throw new Error(step + ": expected the HTTP response status and body.");
  if (status < 200 || status >= 300) {
    const retryAfter = response.headers?.["retry-after"];
    const delay = retryAfter == null ? "" : " Retry-After: " + String(retryAfter) + ".";
    throw new Error(step + " returned HTTP " + status + "." + delay +
      " Keep the original scan key when retrying a submission, or resume by job ID after submission succeeded.");
  }
  if (!response.body || typeof response.body !== "object" || Array.isArray(response.body)) {
    throw new Error(step + ": expected a JSON object in the response body.");
  }
  return response.body;
}

const state = $("Wait before check").item.json;
const response = successfulBody($input.first().json, "Check status");
const checks = state.checks + 1;
const status = response.status;
if (["failed", "cancelled"].includes(status)) {
  throw new Error("Scan " + state.jobId + " ended with status " + status + ". Inspect the job error before starting another scan.");
}
if (!["queued", "waiting", "running", "processing", "completed"].includes(status)) {
  throw new Error("Unexpected job status. Inspect the Check status node output.");
}
if (status !== "completed" && checks >= 20) {
  throw new Error("Stopped after 20 checks. Set resumeJobId to " + state.jobId + " in Audit inputs to keep checking the same job.");
}
return [{ json: { ...state, checks, completed: status === "completed" } }];

The loop stops after 20 checks if the job is still pending. Each HTTP request has a 30-second timeout, and the workflow has a 15-minute execution limit. Reaching a limit does not cancel the API job; use its ID to resume checking.

05 / Make the output useful

Give the next node evidence it can act on

Build review queue turns the report into one n8n item. It retains the page, keyword, region, score, and job ID, then adds a gaps array for editorial review.

gaps

Terms marked missing, absent from the target’s term counts, and present on at least half of the compared pages. Sorted by prevalence, then importance.

originalIdeas

Optional information-gain questions and unique-data-point findings. An unavailable section is distinct from an available but empty list.

nextStep

The application value editorial_review identifies what should happen next. It is added by this workflow.

function buildOptimizer(report, { minCoverage = 0.5, ignoredTerms = [] } = {}) {
  if (minCoverage < 0 || minCoverage > 1 || !Number.isFinite(minCoverage)) {
    throw new Error("minCoverage must be between 0 and 1.");
  }
  const entities = report.entity_coverage?.natural_language_entities;
  const matrix = report.competitor_term_coverage;
  if (!Array.isArray(entities) || !Array.isArray(matrix?.domains) || !Array.isArray(matrix?.terms)) {
    throw new Error("Expected entity_coverage and competitor_term_coverage arrays.");
  }
  const key = (text) => String(text).trim().toLowerCase();
  const statuses = new Map(entities.map((row) => [key(row.entity), row.coverage_status]));
  const ignored = new Set(ignoredTerms.map(key));
  const seen = new Set();
  const gaps = [];
  for (const row of matrix.terms) {
    const counts = row.competitor_counts;
    if (!Array.isArray(counts) || counts.length !== matrix.domains.length ||
        counts.some((n) => typeof n !== "number" || !Number.isFinite(n) || n < 0)) {
      throw new Error("Competitor counts must align with domains and contain numbers.");
    }
    const term = key(row.keyword);
    if (!term || seen.has(term)) continue;
    seen.add(term);
    // Require both signals; present_not_entity is already present in the page.
    if (statuses.get(term) !== "missing" || row.your_url_count !== 0 || ignored.has(term)) continue;
    const competitorPages = counts.filter((n) => n > 0).length;
    const comparedPages = counts.length;
    if (!comparedPages || !competitorPages || competitorPages / comparedPages < minCoverage) continue;
    gaps.push({
      id: "coverage:" + term, term: row.keyword,
      importance: Number.isFinite(row.importance) ? row.importance : 0,
      competitorPages, comparedPages,
      prevalence: competitorPages / comparedPages,
      status: "needs_review",
    });
  }
  gaps.sort((a, b) => b.prevalence - a.prevalence || b.importance - a.importance ||
    (a.term < b.term ? -1 : a.term > b.term ? 1 : 0));
  const gain = report.originality?.information_gain;
  const ideas = gain?.potential_uncovered_topics_for_information_gain;
  return {
    jobId: report.jobId,
    targetUrl: report.meta?.url ?? null,
    keyword: report.meta?.target_keyword ?? null,
    region: report.meta?.location ?? null,
    score: report.on_page_optimization?.score ?? null,
    scoreAlgorithm: report.on_page_optimization?.algorithm_version ?? null,
    comparedPages: matrix.domains.length,
    gaps,
    originalIdeas: {
      available: Array.isArray(ideas),
      items: Array.isArray(ideas) ? [...new Set(ideas.filter((s) => typeof s === "string" && s.trim()))] : [],
      uniqueDataPoints: gain?.unique_data_points ?? null,
    },
  };
}

function successfulBody(response, step) {
  const status = response.statusCode;
  if (typeof status !== "number") throw new Error(step + ": expected the HTTP response status and body.");
  if (status < 200 || status >= 300) {
    const retryAfter = response.headers?.["retry-after"];
    const delay = retryAfter == null ? "" : " Retry-After: " + String(retryAfter) + ".";
    throw new Error(step + " returned HTTP " + status + "." + delay +
      " Keep the original scan key when retrying a submission, or resume by job ID after submission succeeded.");
  }
  if (!response.body || typeof response.body !== "object" || Array.isArray(response.body)) {
    throw new Error(step + ": expected a JSON object in the response body.");
  }
  return response.body;
}

if ($input.all().length !== 1) throw new Error("Expected one completed report.");
const input = $input.first().json;
const report = input.statusCode === undefined ? input : successfulBody(input, "Fetch report");
if (!report.jobId || !report.meta?.url || !report.meta?.target_keyword) {
  throw new Error("Expected the top-level customer_v1 report from the result endpoint.");
}
const review = buildOptimizer(report);
return [{ json: { ...review, nextStep: "editorial_review" } }];

A practical decision from the example

For “testing”, the editor could add a repeatable provider-testing method to the page’s reliability section. “Integration” is already present, so it is excluded from the missing-term queue. “Company” qualifies numerically but can still be dismissed as too generic to justify an edit.

This is why the output is a review queue. Prevalence helps choose what to inspect; it does not decide whether a particular topic improves the page.

Connect it to your product

• One task per page: send the final item to your review system, using jobId to avoid duplicate tasks when a run is resumed.
• One task per suggestion: add a Split Out node for gaps, retain the other fields, and use jobId plus the gap’s id as the deduplication key.
• A client report: save the body JSON from Fetch report and follow the SEO audit PDF tutorial to add reviewed recommendations and generate the document.

The imported workflow ends at the review queue. Add your destination node and its credentials when you’re ready to integrate it. The content optimizer tutorial shows how to turn a selected finding into an editable suggestion.

06 / Developer questions

Keep the workflow predictable

Make SEO analysis a repeatable workflow

You now have a working path from a page URL to a structured review queue: one scan, a bounded polling loop, a resumable job, and a result your next node can use. On-Page.ai supplies the page and competitor analysis; n8n connects it to your team’s process.

Run the saved example, connect your key, and audit a page you want to improve. Then add the review destination that makes those findings useful to your team.