UnrealSEO API Reference

🎯 Quick Summary

Complete REST API for programmatic access to UnrealSEO
Authentication via API keys or OAuth 2.0
Comprehensive endpoints for queries, citations, content, analytics
Webhooks for real-time notifications
Rate limiting and best practices
SDKs available for Python, JavaScript, Ruby, PHP

🔑 Key Concepts at a Glance

Base URL: https://api.unrealseo.com/v1
Authentication: Bearer token in Authorization header
Format: JSON requests and responses
Rate Limit: 1,000 requests/hour (Standard), 10,000/hour (Enterprise)
Webhooks: Real-time event notifications

🏷️ Metadata

Tags: api, reference, developer, technical Status: %%ACTIVE%% Complexity: %%ADVANCED%% Max Lines: 450 (this file: 445 lines) Reading Time: 15 minutes Last Updated: 2025-01-18

API Overview

Base Information

Base URL: https://api.unrealseo.com/v1
Protocol: HTTPS only
Format: JSON
Authentication: Bearer token
API Version: v1 (current)

Quick Start

Your first API call:

curl -X GET "https://api.unrealseo.com/v1/queries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "qry_abc123",
      "query": "best CRM software",
      "citation_rate": 0.75,
      "tracked_since": "2025-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 247,
    "page": 1,
    "per_page": 25
  }
}

Authentication

API Key Authentication

Generate API key:

Login to unrealseo.com
Settings → API Keys
Click "Create New Key"
Name: "Production API"
Permissions: [Select scope]
Click "Generate"
Copy key (shown once!)

Key format: urs_live_abc123def456...

Using API key:

# In header (recommended)
curl -H "Authorization: Bearer urs_live_abc123..." \
  https://api.unrealseo.com/v1/queries

# Query parameter (not recommended)
curl https://api.unrealseo.com/v1/queries?api_key=urs_live_abc123...

OAuth 2.0 (Enterprise)

OAuth flow:

Step 1: Redirect user to authorization URL
GET https://unrealseo.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read_queries,write_queries

Step 2: User authorizes

Step 3: Exchange code for token
POST https://api.unrealseo.com/v1/oauth/token
{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE_FROM_STEP_2",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/callback"
}

Response:
{
  "access_token": "urs_oauth_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "urs_refresh_xyz789..."
}

Step 4: Use access token
Authorization: Bearer urs_oauth_abc123...

Scopes

Available Scopes:

read_queries         Read query data
write_queries        Create/update/delete queries
read_citations       Read citation data
read_content         Read content performance
write_content        Add/update content tracking
read_analytics       Read analytics data
write_webhooks       Create/manage webhooks
admin                Full access (use with caution)

Core Endpoints

Queries

List Queries

GET /v1/queries

Parameters:

page          int     Page number (default: 1)
per_page      int     Results per page (default: 25, max: 100)
status        string  Filter: cited, not_cited, mixed
min_score     int     Minimum query score (0-100)

Example:

curl -X GET "https://api.unrealseo.com/v1/queries?status=cited&min_score=70" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "qry_abc123",
      "query": "best CRM software 2025",
      "citation_rate": 0.75,
      "share_of_voice": 0.14,
      "query_score": 84,
      "platforms": {
        "chatgpt": {"cited": true, "position": 2},
        "claude": {"cited": true, "position": 3},
        "gemini": {"cited": true, "position": 1},
        "perplexity": {"cited": false}
      },
      "tracked_since": "2025-01-01T00:00:00Z",
      "last_checked": "2025-01-18T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 25
  }
}

Create Query

POST /v1/queries

Request:

{
  "query": "CRM implementation cost",
  "platforms": ["chatgpt", "claude", "gemini", "perplexity"],
  "check_frequency": "weekly",
  "tags": ["pricing", "implementation"]
}

Response:

{
  "id": "qry_xyz789",
  "query": "CRM implementation cost",
  "citation_rate": null,
  "status": "pending",
  "created_at": "2025-01-18T11:00:00Z"
}

Get Query

GET /v1/queries/{query_id}

Update Query

PATCH /v1/queries/{query_id}

Delete Query

DELETE /v1/queries/{query_id}

Test Query Now

POST /v1/queries/{query_id}/test

Triggers immediate citation test across all platforms.

Response:

{
  "query_id": "qry_abc123",
  "status": "testing",
  "estimated_completion": "2025-01-18T11:05:00Z"
}

Citations

Get Citations for Query

GET /v1/queries/{query_id}/citations

Parameters:

platform      string  Filter: chatgpt, claude, gemini, perplexity
from_date     string  ISO 8601 date
to_date       string  ISO 8601 date

Response:

{
  "query_id": "qry_abc123",
  "query": "best CRM software",
  "citations": [
    {
      "id": "cit_123",
      "platform": "chatgpt",
      "cited": true,
      "position": 2,
      "content_url": "https://yoursite.com/crm-guide",
      "answer_excerpt": "...YourCRM is a leading platform for small businesses...",
      "checked_at": "2025-01-18T10:30:00Z"
    },
    {
      "id": "cit_124",
      "platform": "claude",
      "cited": false,
      "checked_at": "2025-01-18T10:30:00Z"
    }
  ],
  "summary": {
    "citation_rate": 0.5,
    "total_platforms": 4,
    "cited_platforms": 2
  }
}

Citation History

GET /v1/queries/{query_id}/citations/history

Parameters:

days          int     Days to look back (default: 90, max: 365)
platform      string  Specific platform

Response:

{
  "query_id": "qry_abc123",
  "history": [
    {
      "date": "2025-01-18",
      "citation_rate": 0.75,
      "platforms": {
        "chatgpt": true,
        "claude": true,
        "gemini": true,
        "perplexity": false
      }
    },
    {
      "date": "2025-01-17",
      "citation_rate": 0.50,
      "platforms": {
        "chatgpt": true,
        "claude": true,
        "gemini": false,
        "perplexity": false
      }
    }
  ]
}

Content

List Content

GET /v1/content

Parameters:

page          int     Page number
per_page      int     Results per page
min_citations int     Minimum citation count
content_type  string  Filter by type

Response:

{
  "data": [
    {
      "id": "cnt_abc123",
      "url": "https://yoursite.com/crm-guide",
      "title": "CRM Software Buyer's Guide 2025",
      "content_type": "guide",
      "total_citations": 47,
      "citation_rate": 0.68,
      "queries_tracked": 87,
      "last_updated": "2025-01-15T00:00:00Z"
    }
  ],
  "meta": {
    "total": 342,
    "page": 1,
    "per_page": 25
  }
}

Add Content

POST /v1/content

Request:

{
  "url": "https://yoursite.com/new-guide",
  "title": "New Guide Title",
  "content_type": "guide",
  "auto_track": true,
  "tags": ["product", "guide"]
}

Get Content Performance

GET /v1/content/{content_id}

Update Content

PATCH /v1/content/{content_id}

Delete Content

DELETE /v1/content/{content_id}

Analytics

Get Summary

GET /v1/analytics/summary

Parameters:

date_range    string  Preset: last_7_days, last_30_days, last_90_days
from_date     string  Custom range start (ISO 8601)
to_date       string  Custom range end

Response:

{
  "period": {
    "from": "2024-12-19",
    "to": "2025-01-18"
  },
  "metrics": {
    "citation_rate": 0.245,
    "citation_rate_change": 0.021,
    "share_of_voice": 0.123,
    "share_of_voice_change": 0.014,
    "answer_equity": 78,
    "answer_equity_change": 3,
    "total_queries": 1247,
    "total_citations": 306,
    "new_citations": 23
  },
  "top_content": [
    {
      "url": "https://yoursite.com/crm-guide",
      "citations": 47,
      "citation_rate": 0.82
    }
  ],
  "platforms": {
    "chatgpt": {"citation_rate": 0.28, "avg_position": 2.8},
    "claude": {"citation_rate": 0.21, "avg_position": 3.1},
    "gemini": {"citation_rate": 0.26, "avg_position": 2.4},
    "perplexity": {"citation_rate": 0.23, "avg_position": 2.2}
  }
}

Get Trends

GET /v1/analytics/trends

Parameters:

metric        string  citation_rate, share_of_voice, answer_equity
granularity   string  daily, weekly, monthly
days          int     Trend period (default: 90)

Get Competitors

GET /v1/analytics/competitors

Response:

{
  "your_company": {
    "share_of_voice": 0.123,
    "rank": 3
  },
  "competitors": [
    {
      "name": "Competitor A",
      "share_of_voice": 0.187,
      "rank": 1
    },
    {
      "name": "Competitor B",
      "share_of_voice": 0.157,
      "rank": 2
    }
  ]
}

Webhook Events

Create Webhook

POST /v1/webhooks

Request:

{
  "url": "https://yourapp.com/webhooks/unrealseo",
  "events": ["citation.gained", "citation.lost", "query.milestone"],
  "secret": "your_webhook_secret_for_verification"
}

Response:

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/unrealseo",
  "events": ["citation.gained", "citation.lost", "query.milestone"],
  "status": "active",
  "created_at": "2025-01-18T11:00:00Z"
}

Webhook Events

citation.gained

Triggered when a new citation is detected.

{
  "event": "citation.gained",
  "timestamp": "2025-01-18T14:30:00Z",
  "data": {
    "query_id": "qry_abc123",
    "query": "best CRM software",
    "platform": "chatgpt",
    "position": 2,
    "content_id": "cnt_xyz789",
    "content_url": "https://yoursite.com/crm-guide",
    "previous_status": "not_cited"
  }
}

citation.lost

Triggered when an existing citation is removed.

query.milestone

Triggered when citation rate crosses milestone (25%, 50%, 75%, 100%).

content.optimized

Triggered when content optimization is applied.

Webhook Verification

Verify webhook signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    """Verify webhook signature"""
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# Usage
payload = request.body  # Raw request body
signature = request.headers['X-UnrealSEO-Signature']
secret = 'your_webhook_secret'

if verify_webhook(payload, signature, secret):
    # Process webhook
    data = json.loads(payload)
else:
    # Invalid signature
    return 401

Rate Limits & Errors

Rate Limiting

Rate limits by plan:

Plan          Requests/Hour   Burst
----          -------------   -----
Free          100             10
Standard      1,000           100
Pro           5,000           500
Enterprise    10,000          1,000

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705586400

Rate limit exceeded response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Limit: 1000/hour",
    "retry_after": 3600
  }
}

Error Codes

HTTP Status Codes:

OK                Success
Created           Resource created
No Content        Success (no response body)
Bad Request       Invalid request
Unauthorized      Invalid/missing API key
Forbidden         Insufficient permissions
Not Found         Resource not found
Too Many Requests Rate limit exceeded
Server Error      Internal error
Service Unavailable  Temporary unavailable

Error Response Format:

{
  "error": {
    "code": "validation_error",
    "message": "Query text is required",
    "field": "query",
    "details": {
      "validation": "required"
    }
  }
}

Common Error Codes:

invalid_api_key       API key is invalid
insufficient_scope    API key lacks required scope
validation_error      Request validation failed
resource_not_found    Requested resource doesn't exist
rate_limit_exceeded   Too many requests
internal_error        Server error (contact support)

SDKs & Libraries

Official SDKs

Python

pip install unrealseo

from unrealseo import UnrealSEO

client = UnrealSEO(api_key='urs_live_abc123...')

# List queries
queries = client.queries.list(status='cited', min_score=70)

for query in queries:
    print(f"{query.query}: {query.citation_rate}")

# Create query
new_query = client.queries.create(
    query='CRM implementation guide',
    platforms=['chatgpt', 'claude', 'gemini', 'perplexity'],
    check_frequency='weekly'
)

# Get citations
citations = client.queries.get_citations(query_id='qry_abc123')

JavaScript/Node.js

npm install unrealseo

const UnrealSEO = require('unrealseo');

const client = new UnrealSEO({ apiKey: 'urs_live_abc123...' });

// Async/await
const queries = await client.queries.list({ status: 'cited' });

// Promises
client.queries.list({ status: 'cited' })
  .then(queries => {
    queries.forEach(query => {
      console.log(`${query.query}: ${query.citationRate}`);
    });
  });

// Create query
const newQuery = await client.queries.create({
  query: 'CRM implementation guide',
  platforms: ['chatgpt', 'claude'],
  checkFrequency: 'weekly'
});

Ruby

gem install unrealseo

require 'unrealseo'

client = UnrealSEO::Client.new(api_key: 'urs_live_abc123...')

# List queries
queries = client.queries.list(status: 'cited', min_score: 70)

queries.each do |query|
  puts "#{query.query}: #{query.citation_rate}"
end

PHP

composer require unrealseo/unrealseo-php

use UnrealSEO\UnrealSEOClient;

$client = new UnrealSEOClient('urs_live_abc123...');

// List queries
$queries = $client->queries->list([
    'status' => 'cited',
    'min_score' => 70
]);

foreach ($queries as $query) {
    echo "{$query->query}: {$query->citation_rate}\n";
}

Best Practices

Efficient API Usage

1. Use pagination wisely

# Bad: Fetching all at once
queries = client.queries.list(per_page=10000)  # May timeout

# Good: Iterate through pages
page = 1
while True:
    queries = client.queries.list(page=page, per_page=100)
    if not queries:
        break

    for query in queries:
        process(query)

    page += 1

2. Cache responses

import time

cache = {}
CACHE_TTL = 3600  # 1 hour

def get_queries(status='cited'):
    cache_key = f'queries_{status}'

    if cache_key in cache:
        cached_time, data = cache[cache_key]
        if time.time() - cached_time < CACHE_TTL:
            return data

    data = client.queries.list(status=status)
    cache[cache_key] = (time.time(), data)

    return data

3. Batch operations

# Bad: Individual creates
for query_text in queries:
    client.queries.create(query=query_text)  # 100 API calls

# Good: Bulk create
client.queries.bulk_create(queries=[
    {'query': q} for q in queries
])  # 1 API call

4. Use webhooks for real-time updates

# Bad: Polling
while True:
    citations = client.queries.get_citations(query_id)
    if citations.citation_rate > 0.5:
        alert()
    time.sleep(60)  # Poll every minute

# Good: Webhook
# Set up webhook once, get notified when citation_rate changes
client.webhooks.create(
    url='https://yourapp.com/webhook',
    events=['citation.gained']
)

Platform:

Advanced:

🆘 Need Help?

API Support:

Report Issues:

Last updated: 2025-01-18 | Edit this page

🎯 Quick Summary​

📋 Table of Contents​

🔑 Key Concepts at a Glance​

🏷️ Metadata​

API Overview​

Base Information​

Quick Start​

Authentication​

API Key Authentication​

OAuth 2.0 (Enterprise)​

Scopes​

Core Endpoints​

Queries​

Citations​

Content​

Analytics​

Webhook Events​

Create Webhook​

Webhook Events​

Webhook Verification​

Rate Limits & Errors​

Rate Limiting​

Error Codes​

SDKs & Libraries​

Official SDKs​

Best Practices​

Efficient API Usage​

📚 Related Topics​

🆘 Need Help?​

🎯 Quick Summary

📋 Table of Contents

🔑 Key Concepts at a Glance

🏷️ Metadata

API Overview

Base Information

Quick Start

Authentication

API Key Authentication

OAuth 2.0 (Enterprise)

Scopes

Core Endpoints

Queries

Citations

Content

Analytics

Webhook Events

Create Webhook

Webhook Events

Webhook Verification

Rate Limits & Errors

Rate Limiting

Error Codes

SDKs & Libraries

Official SDKs

Best Practices

Efficient API Usage

📚 Related Topics

🆘 Need Help?