API Documentation | InstaRank SEO

Authentication

All API endpoints require authentication via the X-API-Key header.

Getting an API Key

Sign in to your InstaRank SEO account
Go to Settings > API Keys
Generate a new API key
Store it securely -- it won't be shown again

Using your API Key

curl -X POST https://instarankseo.com/api/v1/checks/robots-txt \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

Validate your key

GET/api/v1/auth

curl -H "X-API-Key: your-api-key-here" https://instarankseo.com/api/v1/auth

Rate Limits

Free Tier

5 audits per month
10 keyword research units per day
1 backlink check per month

Pro Tier

50 audits per month
500 keyword research units per day
10 backlink checks per month

Response Format

All responses are JSON. Successful responses include "success": true and the check results. Error responses include "success": false and an error message.

Success Response

{
  "success": true,
  "check": "robots-txt",
  "url": "https://example.com",
  "domain": "example.com",
  "score": 85,
  "issues": [
    {
      "id": "no-sitemap-reference",
      "title": "No sitemap reference",
      "description": "robots.txt does not reference a sitemap",
      "severity": "moderate",
      ...
    }
  ],
  "data": { ... },
  "checkedAt": "2026-03-16T12:00:00.000Z"
}

Error Response

{
  "success": false,
  "error": "url is required and must be a string",
  "errorType": "INVALID_URL"
}

SEO Check Endpoints

Each check analyzes the homepage of the provided URL. All endpoints accept a JSON body with a url field and return a score, issues, and detailed data.

Error Codes

HTTP Status	Error Type	Description
400	INVALID_URL / INVALID_CHECK / INVALID_REQUEST	Bad request. Check your URL format, check name, or request body.
401	AUTH_REQUIRED	Missing or invalid API key.
429	RATE_LIMIT	Rate limit exceeded. Wait and try again.
500	INTERNAL_ERROR	Server error. The check failed unexpectedly.
502	DNS_ERROR / CONNECTION_REFUSED / SSL_ERROR	Could not reach the target website.
504	TIMEOUT	The check timed out (target site too slow or unresponsive).

Quick Start Examples

Python

import requests

API_KEY = "your-api-key"
BASE_URL = "https://instarankseo.com/api/v1"

response = requests.post(
    f"{BASE_URL}/checks/meta-tags",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={"url": "example.com"},
)

data = response.json()
print(f"Score: {data['score']}/100")
print(f"Issues: {len(data.get('issues', []))}")
for issue in data.get("issues", []):
    print(f"  [{issue['severity']}] {issue['title']}")

JavaScript / Node.js

const API_KEY = "your-api-key";
const BASE_URL = "https://instarankseo.com/api/v1";

const response = await fetch(`${BASE_URL}/checks/robots-txt`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "example.com" }),
});

const data = await response.json();
console.log(`Score: ${data.score}/100`);
console.log(`Issues: ${data.issues?.length ?? 0}`);

Batch analysis (all checks)

# Run all 19 checks for a single URL
CHECKS=(robots-txt sitemap meta-tags canonical-url http-status url-structure \
  internal-links external-links outbound-links mixed-content x-robots-tag \
  keywords content-quality eeat page-speed backlinks llm-optimization \
  social-media spam-score)

for check in "${CHECKS[@]}"; do
  echo "Running $check..."
  curl -s -X POST "https://instarankseo.com/api/v1/checks/$check" \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"url": "example.com"}' | jq '{check: .check, score: .score}'
done

InstaRank SEO API