n8n-nodes-rankability

An official n8n community node for Rankability — the AI-powered SEO platform. Connect your automation workflows to Rankability's content generation, rank tracking, keyword research, page auditing, and optimization tools.

Contents

• Installation
• Credentials
• Resources & Operations
  • Copywriter
  • Reporter
  • Researcher
  • Page Auditor
  • Client
  • Optimize
• Trigger Node
• Starter Workflows
• Long-Running Jobs
• Rate Limits & Retries

Installation

Self-hosted n8n (recommended)

In your n8n instance, go to Settings → Community Nodes → Install, search for n8n-nodes-rankability, and click Install.

Or install manually from the CLI:

npm install n8n-nodes-rankability

Then restart your n8n instance.

n8n Cloud

Community nodes are supported on n8n Cloud. Go to Settings → Community Nodes → Install and search for n8n-nodes-rankability.

Credentials

1. In Rankability, go to Settings → API Keys and create a new key with the scopes you need.
2. Copy the rk_live_... key — it is shown only once.
3. In n8n, add a new Rankability API credential, paste your key, and click Save & Test. The credential test calls GET /clients to verify your key is valid.

Required scopes per resource:

| Resource | Scopes needed | |---|---| | Copywriter | copywriter:run, copywriter:read | | Reporter | reporter:read, reporter:run, reporter:write | | Researcher | researcher:run, researcher:read | | Page Auditor | page_audit:write, page_audit:read | | Client | clients:read, clients:write | | Optimize | optimize:run |

Resources & Operations

Copywriter

Create SEO content jobs, poll status, and retrieve finished content.

| Operation | Description | Scopes | |---|---|---| | Create Job | Creates a content job and optionally waits for completion | copywriter:run, copywriter:read | | Get Job | Returns status and progress of a job | copywriter:read | | Approve Brief | In stepped mode, approves the brief to trigger draft generation | copywriter:run | | List Jobs | Lists all content jobs, with optional filters | copywriter:read |

Create Job — key fields:

| Field | Description | |---|---| | Topic / Keyword | The primary keyword (e.g., emergency plumber st louis) | | Intent | educate / discover / compete / convert | | Mode | auto (full pipeline) or stepped (pause at brief) | | Wait for Completion | If enabled, the node blocks and polls until complete, then returns the finished content | | Tone | Writing tone for the generated draft | | Word Count Target | Target length (100–10,000 words) |

When Wait for Completion is enabled (default), the node handles the full async lifecycle: Create → Poll → Return. You do not need to chain separate poll and fetch steps.

Reporter

Manage rank tracking projects and access SPI scores across Google, ChatGPT, Perplexity, and Gemini.

| Operation | Description | Scopes | |---|---|---| | List Projects | Lists all rank tracking projects | reporter:read | | Create Project | Creates a new tracking project with keywords and platforms | reporter:write | | Get Results | Returns the latest SPI scores and ranking data for a project | reporter:read | | Trigger Scan | Triggers a manual rank tracking scan | reporter:run | | Get Summary | Returns org-wide summary: average SPI, active projects, top movers | reporter:read |

Researcher

Start keyword research jobs and fetch keyword clusters with volume and difficulty data.

| Operation | Description | Scopes | |---|---|---| | Start Research | Starts a research job and optionally waits for completion | researcher:run, researcher:read | | Get Results | Returns results for a completed research job | researcher:read | | List Jobs | Lists recent research jobs | researcher:read |

Research modes: discover, trending, reddit, youtube, ecommerce

When Wait for Completion is enabled (default), the node polls until the research completes and returns keyword clusters, volume, and difficulty scores.

Page Auditor

Audit any public URL against a target keyword. Each audit costs 100 credits.

| Operation | Description | Scopes | |---|---|---| | Run Audit | Starts a page audit and optionally waits for completion | page_audit:write, page_audit:read | | Get Audit | Returns full audit results by ID | page_audit:read | | List Audits | Lists audits with optional status and client filters | page_audit:read |

Run Audit checks: crawlability, indexability, retrievability (AI-agent gate), keyword placement, entity coverage, schema, technical health, and Page Speed Insights. Credits are refunded if the page fails a gate or the audit errors out.

When Wait for Completion is enabled, the node polls until the audit is complete (typically 60–180 seconds).

Client

Manage client profiles with brand voice and domain context.

| Operation | Description | Scopes | |---|---|---| | List | Lists all clients | clients:read | | Get | Gets a client by UUID | clients:read | | Create | Creates a new client | clients:write | | Update | Updates an existing client | clients:write |

Optimize

Score any public page against its SERP competitors. Each call costs 1,200 credits and takes 30–90 seconds.

| Operation | Description | Scopes | |---|---|---| | Run | Scores a URL against the top SERP results for a keyword | optimize:run |

Returns a Rankability score (0–100), entity coverage analysis, and competitor benchmarks. Results are cached for 24 hours — a duplicate call for the same URL+keyword returns the cached result without re-deducting credits.

Trigger Node

The Rankability Trigger node polls a specific async job until it reaches a terminal state, then fires the workflow once.

Use case: Start a Copywriter job with a separate node or API call, note the job ID, then use the Trigger node to run downstream automation when the job completes.

Fields:

| Field | Description | |---|---| | Job Type | Copywriter Job, Researcher Job, or Page Auditor | | Job ID / Audit ID | UUID of the job to monitor | | Emit on Failure | If enabled, also fires when the job fails | | Include Artifacts | (Copywriter only) Fetches and includes the completed content artifacts |

The trigger fires once and records its state in workflow static data. To re-arm it for a new job, create a new trigger instance or reset the workflow's static data.

Starter Workflows

Three workflow JSON files are included in the workflows/ directory. Import them via n8n → Import Workflow.

1. Copywriter from Google Sheets

workflows/copywriter-from-google-sheets.json

Watches a Google Sheet for new keyword rows. When a new row is added (with columns keyword and intent), creates a Rankability Copywriter job and writes the job ID and status back to a results sheet.

Setup: Replace YOUR_GOOGLE_SHEET_ID with your sheet ID and configure your Google Sheets and Rankability credentials.

2. Weekly Reporter Digest to Slack

workflows/weekly-reporter-digest-to-slack.json

Runs every Monday at 8am. Pulls your Rankability Reporter summary and top tracked projects, then posts a formatted digest to a Slack channel.

Setup: Set your Slack channel and configure your Slack and Rankability credentials.

3. Bulk Page Auditor from URL List

workflows/bulk-page-auditor-from-url-list.json

Reads a CSV file (urls.csv) with columns url, keyword, and optionally location. Runs a Rankability Page Audit on each URL, waits for completion, then aggregates all scores into a summary object.

Setup: Provide a CSV file and configure your Rankability credential. Each row costs 100 credits.

Long-Running Jobs

Copywriter jobs (auto mode) typically take 3–8 minutes. Researcher jobs take 1–3 minutes. Page Auditor jobs take 1–3 minutes.

When Wait for Completion is enabled, the node polls on a 5-second interval (8-second for Page Auditor) with a default 10-minute timeout. For workflows where you do not want to block, disable Wait for Completion and use the Rankability Trigger node to fire downstream automation when the job finishes.

Rate Limits & Retries

The node automatically respects Rankability's rate limits:

• On a 429 Too Many Requests response, the node reads the Retry-After header and backs off before retrying, up to 3 times.
• Every mutating request (POST, PATCH) includes a unique Idempotency-Key header, so retries from n8n's built-in retry mechanism are safe and will not create duplicate jobs.
• Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are passed through by the Rankability API on every response.

The Rankability API allows 60 requests/minute and 10,000 requests/day per key.

Support

• Documentation: rankability.com/docs/integrations/n8n
• API Reference: rankability.com/docs/agent-api
• Support: [email protected]