LucidRank/API Reference

LucidRank API

Programmatically run AI visibility audits, retrieve results, and get notified via webhooks. Audits measure how your brand appears across ChatGPT, Gemini, and Claude.

Base URLhttps://www.lucidrank.io/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from Dashboard → Settings → API Keys.

Example

curl https://www.lucidrank.io/api/v1/usage \
  -H "Authorization: Bearer lr_live_your_key_here"

API access requires a Pro plan or above. Free and Starter accounts cannot use the API.

Rate Limits

API requests are rate-limited per key. Every response includes headers showing your current usage:

X-RateLimit-LimitMax requests per minute

X-RateLimit-RemainingRequests left in window

X-RateLimit-ResetUnix timestamp when window resets

Pro: 30 req/min · Business: 60 req/min

Monthly audit quotas are shared between the web app and API. A global concurrency limit of 10 simultaneous audits applies system-wide.

Create Audit

POST/api/v1/audits

Start a new AI visibility audit. Returns immediately with the audit ID; processing happens in the background.

Request Body

domainstring*

Domain to audit (e.g. "example.com"). No protocol prefix.

keywordsstring[]

Optional keywords for competitor discovery.

locationstring

Optional geographic location for localized results.

curl

curl -X POST https://www.lucidrank.io/api/v1/audits \
  -H "Authorization: Bearer lr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "keywords": ["saas analytics"]}'

Response (202 Accepted)

{
  "data": {
    "id": "a1b2c3d4-...",
    "domain": "example.com",
    "status": "pending",
    "created_at": "2026-02-28T12:00:00Z",
    "status_url": "https://www.lucidrank.io/api/v1/audits/a1b2c3d4-..."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-28T12:00:00Z"
  }
}

Get Audit

GET/api/v1/audits/:id

Retrieve audit details and results. Poll this endpoint to track progress.

Query Parameters

fieldsstring

Comma-separated list of fields to include. Options:

score, score_breakdown, recommendations, ai_results, competitor_analysis, competitive_intelligence, keyword_opportunities, brand_perception, structured_data_audit, quick_wins, executive_summary, website_analysis

curl

# Full results
curl https://www.lucidrank.io/api/v1/audits/AUDIT_ID \
  -H "Authorization: Bearer lr_live_..."

# Only score and recommendations
curl "https://www.lucidrank.io/api/v1/audits/AUDIT_ID?fields=score,recommendations" \
  -H "Authorization: Bearer lr_live_..."

List Audits

GET/api/v1/audits

List your audits with pagination and optional filters.

statusstring

Filter by status: pending, processing, completed, failed

domainstring

Filter by domain

limitnumber

Results per page (default 20, max 100)

offsetnumber

Offset for pagination (default 0)

curl

curl "https://www.lucidrank.io/api/v1/audits?status=completed&limit=10" \
  -H "Authorization: Bearer lr_live_..."

Cancel Audit

DELETE/api/v1/audits/:id

Cancel a pending audit. Only audits with status 'pending' can be cancelled.

curl

curl -X DELETE https://www.lucidrank.io/api/v1/audits/AUDIT_ID \
  -H "Authorization: Bearer lr_live_..."

Usage

GET/api/v1/usage

Check your current quota and rate limit status.

Response

{
  "data": {
    "subscription_tier": "pro",
    "audits": {
      "used": 12,
      "limit": 25,
      "remaining": 13
    },
    "rate_limit": {
      "requests_per_minute": 30,
      "remaining": 28,
      "reset_at": "2026-02-28T12:01:00Z"
    }
  }
}

Webhooks

Configure a webhook URL when creating your API key to receive notifications when audits complete or fail. The payload is signed with HMAC-SHA256 using your webhook secret.

Webhook Payload

{
  "event": "audit.completed",
  "audit": {
    "id": "a1b2c3d4-...",
    "domain": "example.com",
    "status": "completed",
    "visibility_score": 72,
    "pure_visibility_score": 72,
    "score_breakdown": { ... },
    "created_at": "2026-02-28T12:00:00Z",
    "completed_at": "2026-02-28T12:03:15Z"
  },
  "timestamp": "2026-02-28T12:03:15Z"
}

Signature Verification

Verify the X-LucidRank-Signature header by computing HMAC-SHA256 of the raw request body using your webhook secret:

Node.js

import { createHmac } from 'crypto';

function verifyWebhook(body, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === expected;
}

Python

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Errors

All errors follow a consistent format with an error code and human-readable message:

Error Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "retry_after": 30
  }
}

Code	Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions or plan
`not_found`	404	Resource not found
`invalid_request`	400	Bad request parameters
`rate_limit_exceeded`	429	Too many requests
`monthly_limit_reached`	429	Monthly audit quota used up
`domain_limit_reached`	403	Domain limit for your plan
`invalid_state`	409	Action not allowed in current state
`internal_error`	500	Server error

Need help? Contact support