The same surface that powers the dashboard.

What it does

The REST API exposes the same operations as the dashboard:

• Onboard new clients automatically. Hand the API a website URL. It researches the brand, proposes competitors and buyer-intent topics, and creates the project with prompts ready to scan.
• Run AI visibility scans across ChatGPT, Perplexity, Google AI Overviews, and DeepSeek. (Claude is gated to specific accounts.)
• Read visibility, share of voice, sentiment, citation sources, and per-attribute breakdowns programmatically.
• Download client-ready PDF reports.
• Manage projects, topics, prompts, and platforms.

Authentication

Every request needs a Clerk API key in the Authorization header.

Get an API key

1. Sign in to OpenLens. If you don't have an account yet, sign up here. The API doesn't provision accounts in beta, so the web sign-up is the only path.
2. From the dashboard, click your avatar in the bottom-left corner and choose Manage account.
3. Open the API Keys tab and click Add new key.
4. Give the key an optional name (handy if you're running it from multiple machines) and pick an expiration date.
5. Copy the secret immediately. It never appears again. If you lose it, you'll need to revoke it and create a new one.

Send it on every request

Authorization: Bearer <your_api_key>

Base URL

https://openlens.com/api

Responses are JSON unless otherwise noted. The PDF report endpoint returns application/pdf.

End-to-end example

We'll onboard Anthropic from scratch and read back their visibility scores. Five short steps, about 11 minutes end to end (30 seconds to analyze the brand, 1 minute to generate prompts, 10 minutes to run the scan across every platform). The individual steps are short on their own; the wait is the AI platforms thinking.

Setup

Pin the base URL and the auth header so every request below can reuse them. YOUR_API_KEY is the secret you copied from the dashboard above.

import json
import time
import requests

BASE = "https://openlens.com/api"
auth = {"Authorization": "Bearer YOUR_API_KEY"}

Step 1: Analyze the brand (about 30s)

POST /onboard with action: "analyze" hands the API a website URL. It reads the page, figures out what the brand does, and proposes a starting set of competitors and buyer-intent topics. Nothing is saved yet, so you can edit the result before committing. The endpoint streams progress events as Server-Sent-Events; we just wait for the full response and parse the final data: line.

res = requests.post(
    f"{BASE}/onboard",
    headers=auth,
    json={"action": "analyze", "url": "https://anthropic.com/"},
)
analysis = json.loads(res.text.strip().split("data: ")[-1])["data"]

Step 2: Confirm and create the project (about 1m)

action: "confirm" takes the analysis back (with any edits you want), creates the project, and generates 10 prompts per topic in the background. This is the step that actually persists data. activePlatforms picks which AI engines we'll scan against; the four below are available to every account.

res = requests.post(f"{BASE}/onboard", headers=auth, json={
    "action": "confirm",
    "brandName": analysis["brandName"],
    "url": "https://anthropic.com/",
    "industryType": analysis["industryType"],
    "location": analysis["location"],
    "languages": analysis["languages"],
    "competitors": analysis["competitors"],
    "topicList": analysis["topics"],
    "activePlatforms": ["chatgpt_app", "perplexity_app", "google_app", "deepseek"],
    "promptsPerTopic": 10,
})
project_id = json.loads(res.text.strip().split("data: ")[-1])["data"]["projectId"]

Migration note (temporary): the analyze response also emits a legacy keywords alias for topics, and the confirm body still accepts keywordList as an alias for topicList. Both aliases will be removed in a future release — migrate to topics / topicList.

Step 3: Kick off a scan

POST /prompts/run returns immediately with a runId. The actual work (running every prompt against every active platform) happens in the background. A typical run is 30 prompts × 4 platforms = 120 platform responses.

run_id = requests.post(
    f"{BASE}/prompts/run",
    headers=auth,
    json={"projectId": project_id},
).json()["runId"]

Step 4: Wait for it to finish (5 to 15 minutes)

GET /prompts/status tells you whether the run is still going. Poll every 30 seconds. Most fresh projects complete in 5 to 10 minutes; larger ones can take 30+. If a deploy or crash interrupts a run, calling POST /prompts/run again resumes it from where it left off, no manual cleanup needed.

while (s := requests.get(
    f"{BASE}/prompts/status",
    headers=auth,
    params={"projectId": project_id, "runId": run_id},
).json())["status"] not in ("completed", "failed"):
    time.sleep(30)

Step 5: Read the results

Once the run is complete, GET /visibility returns an array of brand-level scores: visibility (mention rate), share of voice, sentiment, average rank, per-platform breakdown. This is the same data the dashboard renders. Companion endpoints (/visibility/trends, /insights/engines, /brand-mentions-summary) drill into time series, per-platform behavior, and citation sources.

scores = requests.get(
    f"{BASE}/visibility",
    headers=auth,
    params={"projectId": project_id},
).json()

What you get back

Running that script against Anthropic produces something like:

Brand: Anthropic
Competitors: ['OpenAI', 'Google DeepMind', 'Meta AI', 'xAI', 'Mistral AI']
Topics: ['best large language model API for enterprise applications',
         'safest most reliable AI model for business',
         'top frontier AI models compared for developers']
  * Anthropic                  49.2%
    OpenAI                     55.8%
    Google DeepMind             5.8%
    Meta AI                     1.7%
    xAI                         5.8%
    Mistral AI                 14.2%

Supported platforms

To see which platforms are active on your account: GET /api/settings/platforms.

Endpoint families

A quick tour of what's available. Full request and response shapes live in the beta reference.

• Onboarding. POST /api/onboard (Server-Sent Events) with action: analyze or action: confirm.
• Runs. POST /api/prompts/run to start, GET /api/prompts/status to poll, DELETE /api/prompts/run to cancel, GET /api/prompts/results for raw responses.
• Metrics. GET /api/visibility (overall, per-topic, per-attribute), GET /api/visibility/trends for time series, GET /api/insights/engines for per-platform source behavior, GET /api/insights/topic for an AI-generated insight paragraph.
• Citations. GET /api/brand-mentions-summary returns top cited URLs per topic.
• Deliverables. GET /api/reports/visibility returns a client-ready PDF; GET /api/reports/runs returns run history.
• Resources. CRUD endpoints for projects, brands, topics, and prompts. List your projects, add a topic (auto-generates prompts), tweak a prompt template, deactivate prompts you don't want, and so on.
• Account. GET /api/me/limits, GET /api/usage, GET /api/settings/schedule, GET /api/settings/platforms.

Get the full reference

The complete request and response shapes, error codes, and known quirks live in the beta reference doc. We'll publish a versioned, hosted reference once usage stabilizes. In the meantime, email [email protected] for access and we'll share the doc plus raise your rate limits if you need them.

Common errors

Support

Bug reports, rate-limit bumps, integration help: email [email protected].