Quickstart

1. Create an API key

Create an API Key

Go to Settings > API in your Ranked AI dashboard.

Choose your permission level:

Read Only (default) — fetch keywords, audits, backlinks, AI visibility, content, and reports
Read + Write — everything above, plus create reports, manage webhooks, and update preferences

API keys are shown only once when created. Copy and store it securely. Keys are tied to the project owner account and can only access projects you own directly.

2. Find your project ID

Every API call requires a project ID. List your projects to find it:

curl https://app.ranked.ai/api/v1/projects \
  -H "Authorization: Bearer rk_live_your_api_key"

const response = await fetch('https://app.ranked.ai/api/v1/projects', {
  headers: { 'Authorization': 'Bearer rk_live_your_api_key' }
});
const { data } = await response.json();

data.forEach(project => {
  console.log(`${project.name}: ${project.id}`);
});

import requests

response = requests.get(
    'https://app.ranked.ai/api/v1/projects',
    headers={'Authorization': 'Bearer rk_live_your_api_key'}
)
for project in response.json()['data']:
    print(f"{project['name']}: {project['id']}")

Response:

{
  "data": [
    {
      "id": "40596405-c27c-4dfc-89e4-142c87846d66",
      "name": "My Website",
      "status": "active",
      "serviceType": "seo",
      "websiteUrl": "https://example.com"
    }
  ]
}

Copy the id value — you’ll use it in all subsequent calls.

3. Fetch your data

Use the project ID to pull keyword rankings, audit results, AI visibility, and more.

Keyword rankings

curl "https://app.ranked.ai/api/v1/projects/YOUR_PROJECT_ID/rankings/keywords?limit=10" \
  -H "Authorization: Bearer rk_live_your_api_key"

const base = `https://app.ranked.ai/api/v1/projects/${projectId}`;
const headers = { 'Authorization': `Bearer ${apiKey}` };

const response = await fetch(`${base}/rankings/keywords?limit=10`, { headers });
const { data } = await response.json();

data.forEach(kw => {
  console.log(`${kw.keyword}: Desktop ${kw.desktop_position}, Mobile ${kw.mobile_position}, Net Change ${kw.net_change > 0 ? '+' : ''}${kw.net_change}`);
});

import requests

base = f'https://app.ranked.ai/api/v1/projects/{project_id}'
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(f'{base}/rankings/keywords', headers=headers, params={'limit': 10})
for kw in response.json()['data']:
    print(f"{kw['keyword']}: Desktop {kw['desktop_position']}, Net Change {kw['net_change']}")

Each keyword includes positions across four channels:

Field	Description
`desktop_position`	Google Desktop rank
`mobile_position`	Google Mobile rank
`ai_mode_position`	Google AI Mode rank
`maps_position`	Google Maps rank
`net_change`	Combined position change across all channels

What else is available

Endpoint	What it returns
`GET /rankings/keywords`	Keyword positions across Desktop, Mobile, AI Mode, Maps
`GET /prompts`	AI visibility across ChatGPT, Claude, Gemini, Perplexity, Grok, Meta
`GET /audits/latest`	Latest site audit results with issue counts
`GET /backlinks/summary`	Backlink profile with referring domains
`GET /content`	Content calendar with status and scheduling
`GET /reports`	Shareable SEO report links
`POST /webhooks`	Real-time notifications when data changes

See the full API reference for all endpoints and parameters.

Build with AI

Copy this prompt into Cursor, Claude, or ChatGPT to build an integration:

Give this to your AI coding tool to build a Ranked AI integration.

Open in Cursor

Next steps

API Reference

Full endpoint documentation with examples.

Webhooks

Get notified when keyword positions update, content changes, or audits complete.

MCP Integration

Connect Ranked AI to ChatGPT, Claude, or Cursor.

Agency Dashboard

Build a custom client dashboard with the API and webhooks.

Getting Started

MCP Integration

Webhooks

Best Practices

1. Create an API key

Create an API Key

2. Find your project ID

3. Fetch your data

Keyword rankings

What else is available

Build with AI

Next steps

API Reference

Webhooks

MCP Integration

Agency Dashboard

​1. Create an API key

Create an API Key

​2. Find your project ID

​3. Fetch your data

​Keyword rankings

​What else is available

​Build with AI

​Next steps

API Reference

Webhooks

MCP Integration

Agency Dashboard

1. Create an API key

2. Find your project ID

3. Fetch your data

Keyword rankings

What else is available

Build with AI

Next steps