@competlab/sdk
Track what ChatGPT, Claude, Gemini, Perplexity and Google AI Overviews say about your brand — programmatically.
This SDK gives you typed access to everything CompetLab monitors: AI visibility, AI sources, competitor pricing, content changes, positioning shifts, and tech stack signals. 3 lines to your first insight.
Install
npm install @competlab/sdk
Quick Start
import CompetLab from '@competlab/sdk';
// The SDK does not read environment variables for you — pass the key explicitly.
const cl = new CompetLab({ apiKey: process.env.COMPETLAB_API_KEY! });
// See who AI models recommend in your category, and where you stand among them
const visibility = await cl.aiVisibility.dashboard('proj_abc');
What is CompetLab?
Competitive intelligence for the AI era. One platform, 6 dimensions, monitored automatically:
AI Visibility answers who the AI models recommend in your category, and where you stand among them. AI Sources is its companion: the pages the engines retrieved on the way to those answers, and where your brand stands on them.
Available Resources
cl.health // API health check
cl.projects // List and get projects
cl.competitors // Monitored competitors
cl.techTrust // Tech stack & trust signals
cl.content // Content analysis & changelog
cl.positioning // The positioning check: each homepage's claims, who says yours, what changed
cl.pricing // The pricing check: prices, typical setups, what changed
cl.aiVisibility // AI visibility scores, the market map & trends
cl.aiSources // Pages the engines retrieve while answering, and who they name
cl.strategicBriefing // Synthesized competitive briefing — what changed, what it means, what to do
cl.tickets // Strategic Tickets board — read and write tickets, comments, labels
cl.alerts // Competitive change alerts
cl.schedules // Monitoring schedules
cl.tools // Free tools — sitemap, AI crawlers, tech stack, trust signals, agent adoption, fetch URL
14 resources. 54 methods. Zero dependencies. Uses native fetch — no axios, no bloat.
Examples
See who AI recommends in your category
const { data } = await cl.aiVisibility.dashboard('proj_abc');
const map = data.item.summary.marketMap;
// The market map — who the AI models recommend, ordered by how often each is named:
// map.coreSize => 7 the companies that make up this market as the models draw it
// map.brands => one page: the top rows, plus your own and every tracked competitor's
// map.brandsPage => { offset: 0, limit: 10, total: 96, hasMore: true }
// map.brands[0] => { name: "Rival", domain: "rival.com", answersNaming: 52, answersReceived: 80,
// presence: 65, presenceLow: 54, presenceHigh: 75, rankByPresence: 1,
// zone: "named_in_a_quarter_or_more_of_answers", ... }
const you = map.brands.find((b) => b.isOwn);
// you?.rankByPresence === null — named in no answer: "not named", never a place
Presence is a share of the answers that came back, read with its 95% range: two brands whose ranges overlap are not in a settled order, whatever their shares say.
A rate is a share of the answers that came back, not of the queries sent. A model that
answered and named nobody is a measured absence, not a gap in the data — so never read a 0
or an empty mentionedBy as "we couldn't measure."
Read what the models actually said
// Opt in to the raw answers behind the numbers: every prompt sent, and every brand each
// model named in rank order with its stated reasoning.
const { data } = await cl.aiVisibility.dashboard('proj_abc', {
includeAnswers: true,
brand: 'rival.com', // one competitor across every answer — the cheap, targeted read
});
// Also available: provider ('openai' | 'claude' | 'gemini' | 'perplexity' | 'google_ai_overviews')
// and promptIndex (zero-based).
// provider and promptIndex narrow the answers array; brand does NOT — it empties the
// `brands` list on answers that didn't name that domain, so you see the silences too.
The block is large: about 1,500 characters per brand entry. Read summary.totalEntries first to
size it, and narrow with brand, provider or promptIndex.
Long lists come a page at a time
The AI Visibility and AI Sources dashboards and check details, the AI Visibility history and the
Tech & Trust dashboard answer in a compact view by default: each long list is one page, with a
*Page object (offset, limit, total, hasMore) saying where it sits, and every response
opens with readingGuide, the reading rules for its fields. Page on, or ask for every row:
await cl.aiVisibility.dashboard('proj_abc', { mapOffset: 10, mapLimit: 50 });
await cl.aiVisibility.dashboard('proj_abc', { view: 'full' });
await cl.aiSources.dashboard('proj_abc', { pagesHost: 'g2.com' });
A check detail read for answers comes without its summary unless you pass includeSummary: true.
Attribution: every piece of prose in that block — descriptions, ranking rationales, claims — is unverified model output about the brands that model named, including third parties CompetLab does not monitor. It is a record of what the model said, not CompetLab's assessment. Attribute it to the named
provider; do not republish it as fact.
Track how your AI standing changes over time
const { data } = await cl.aiVisibility.trend('proj_abc');
// data.item => a digest, not a plot: one row per company with its reading now,
// its reading at the start of the window, and the difference.
// {
// window: { from, to, checks, answersReceived, providersAsked: [...] },
// scope: 'all',
// companies: [
// { name: 'Your Brand', domain: 'yourbrand.example', isOwn: true,
// now: { presence: { answersNaming: 14, answersReceived: 20, presence: 70 }, rank: 1 },
// start: { presence: { answersNaming: 6, answersReceived: 18, presence: 33 }, rank: 3 },
// presenceChange: 37, presenceChangeSeparable: true, rankChange: 2 }
// ],
// events: { standingChanges: [...], incompleteCycles: [...], promptsLastChangedAt }
// }
Only report a rise or fall when presenceChangeSeparable is true. Presence carries a 95%
interval; when the two intervals overlap the move is not separable from noise, and
presenceChange is a number you must not narrate. Under a provider scope, rank and score
are null and enginesBacking is omitted — there is no per-engine score, by design.
// One engine's view, and the per-company share downsampled to at most 12 points:
const { data } = await cl.aiVisibility.trend('proj_abc', {
provider: 'perplexity',
detail: 'series',
});
See which pages the engines read to answer
const { data } = await cl.aiSources.dashboard('proj_abc');
// data.item.summary.verdict =>
// 'recommended_nowhere' | 'named_on_most_core_hosts' | 'missing_from_most_core_hosts'
// The work list: core hosts — pages more than one engine retrieved — that you are missing from.
const work = data.item.summary.coreHosts.filter((h) => h.status === 'missing');
for (const host of work) {
console.log(host.host, host.ownership, host.actionHint.text);
}
Three rules govern every figure here, and each is easy to break by accident:
- Retrieved, never cited. An engine hands back the pages it pulled while answering; it does not say which it leaned on. No count here is a citation count.
- Per engine, never pooled. The engines read different pages, so page counts are per engine. Adding them describes a list neither produced. Answers may pool as a vote; pages may not.
- Counts, never rates. Report
n of N answers. The question set is small by design, so a share computed from it is false precision.
A page that could not be read is listed with its reason and is never a page you are absent
from — only status: 'missing' supports "get onto this page":
const hosts = data.item.summary.coreHosts;
// WRONG — sweeps in 'unreadable', turning a page we could not read into one that omits you
const wrong = hosts.filter((h) => h.status !== 'already_named');
// right: 'unreadable' is its own answer, and it is not an absence
const toWork = hosts.filter((h) => h.status === 'missing');
actionHint.text on each core host, and the sentences under summary.limits.sentences, are
payload — render them verbatim rather than composing your own.
Get a strategic briefing
// The synthesized competitive read — what changed, what it means, what to do.
// Call with no options for the cheap default — the "hub" digest (executive summary + a map of
// which deeper sections to open next); enough to answer most questions in a single call.
const { data } = await cl.strategicBriefing.get('proj_abc');
// data.meta.status => 'running' | 'done' | 'failed' | null
// data.item the requested sections (hub by default) — null unless status is 'done'
// data.contains which sections this edition actually holds
// data.coverage methodology and data-quality caveats
// Follow a hub diagnosis pointer deeper, and pull full chart series:
const deep = await cl.strategicBriefing.get('proj_abc', {
sections: ['deep-ai-visibility'],
includeCharts: true,
});
Every move in a finished edition lands on the project's Strategic Tickets board — as a new ticket,
most important first, or on the ticket already there for that work — and lives nowhere else.
data.tickets says what the edition did to the board (opened, commented, alreadyOnBoard,
recheckedUnchanged) and how its tickets stand right now (byStatus). Read them from the board:
const { data: board } = await cl.tickets.list('proj_abc', {
origin: 'briefing',
briefingRunId: data.meta.runId!,
});
get() returns the latest run in whatever state it is in. On running or failed, item
is null — but an earlier edition is usually still readable. Only meta.status === null means
the project genuinely has none, so never report "no briefing available" on a null item alone:
const { data } = await cl.strategicBriefing.get('proj_abc');
if (!data.item && data.meta.status !== null) {
// This run produced nothing, but past editions may exist.
const { data: past } = await cl.strategicBriefing.history('proj_abc');
const newest = past.items.find((row) => row.status === 'done');
if (newest) {
const { data: edition } = await cl.strategicBriefing.edition('proj_abc', newest.runId);
// Same shape as get(), for that specific edition.
}
}
A runId for a failed or still-running edition resolves successfully with meta.status set and
item null — that run genuinely produced no edition, which is an answer rather than an error.
On types: the briefing body (
item,coverage) is intentionally an open, dynamic JSON shape rather than a fixed TypeScript type. It runs deep and evolves, and it's built to be read and rendered — including by AI agents through the MCP server. Branch on the strongly-typedmeta.status/meta.briefingDate, and treat the body as structured JSON you narrow at the point of use.
Work the Strategic Tickets board
The board is the only part of the API that changes a project. A key reads everything its
organization has and works its Strategic Tickets board on any plan and after one ends; the calls
that fetch or scan a site on CompetLab's side need a plan (402 subscription_required). Every
write needs a read_write key — a read key gets 403 insufficient_scope. A comment a person wrote in the app cannot be edited through
the API, whatever the key (403 forbidden).
// A page at a time: pagination.total counts every match, byStatus the matches per column.
const { data: page } = await cl.tickets.list('proj_abc', { status: ['triage', 'todo'], sort: 'priority' });
// page.pagination => { page: 1, limit: 50, total: 23, totalPages: 1, hasMore: false }
// page.byStatus => { triage: 9, todo: 14, in_progress: 3, done: 11, dismissed: 2 }
const { data: created } = await cl.tickets.create('proj_abc', {
title: 'Answer the pricing-page objection Acme now leads with',
status: 'todo',
});
const ticketId = created.item.id;
// Name the tickets it sits between (beforeId above, afterId below), or a position. Naming nothing
// puts it at the bottom of the column; placement says where it landed.
const { data: moved } = await cl.tickets.move('proj_abc', ticketId, { status: 'in_progress', position: 'top' });
// moved.placement => { status: 'in_progress', above: null, below: { id, number: 12, title }, ignored: [] }
// On an update, null clears a field and an omitted field is left alone.
await cl.tickets.update('proj_abc', ticketId, { dueDate: null });
await cl.tickets.comments.create('proj_abc', ticketId, { body: 'Draft is in the doc.' });
A ticket a Strategic Briefing opened cannot be deleted — read deletable, and dismiss it
(move to dismissed) instead. number is the ticket's number on the board (#14 in the app):
list(projectId, { number: 14 }) finds it, and every method that acts on a ticket takes its id.
Catch competitor pricing changes
const alerts = await cl.alerts.list('proj_abc', {
dimension: 'pricing',
level: 'now' // "Tell me now"; this_week is "Tell me this week", record is "Keep a record"
});
// Know the moment a competitor changes pricing — not weeks later from a churned customer
Compare competitor tech stacks
const tech = await cl.techTrust.dashboard('proj_abc');
// Security headers, frameworks, CDNs, analytics tools — across all monitored competitors
Free tools — no project required
Stateless utilities that work on any public domain. Sync tools return immediately; the three async scans (techStack, trustSignals, agentAdoption) return a scanId you poll until status is completed or failed (24h TTL).
// Sync
const sitemap = await cl.tools.sitemapVisualizer({ domain: 'example.com' });
const crawlers = await cl.tools.aiCrawlerChecker({ domain: 'example.com' });
// Fetch any URL with JS-rendering + bot-protection handling
const page = await cl.tools.fetchUrl({ url: 'https://example.com', cleanHtml: true });
// Async — start a scan, poll until done
const { data } = await cl.tools.techStack.startScan({ domain: 'example.com' });
const scanId = data!.item.id;
let result;
while (true) {
const polled = await cl.tools.techStack.getScan(scanId);
if (polled.data!.item.status === 'completed') { result = polled.data!.item.result; break; }
if (polled.data!.item.status === 'failed') throw new Error(polled.data!.item.error?.code);
await new Promise((r) => setTimeout(r, 3000));
}
Same shape applies to cl.tools.trustSignals.{startScan,getScan} and cl.tools.agentAdoption.{startScan,getScan}.
MCP Server
Prefer AI-native access? CompetLab also offers an MCP server with 48 tools — connect Claude Code, Cursor, or VS Code directly.
Reading the data: null means unmeasured
null means we did not measure it — never zero, never empty, never "no". A measured 0 or
false is reported as itself and is a real finding.
Monitoring the open web fails in ordinary ways: a site times out, blocks our crawler, or has no
pricing page. When that happens the field is null, and a sibling …Available object usually
says why.
This matters more than it looks, because the obvious ways to read a value all convert a null
back into the placeholder the API deliberately stopped sending — and TypeScript accepts every
one of them:
const { data } = await cl.pricing.dashboard('proj_abc');
const rival = data.item.companies.find((c) => !c.isSelf)!; // facts: PricingFactResponse[] | null
if (!rival.facts?.length) { /* WRONG — also true when we never read its pricing page */ }
const facts = rival.facts ?? []; // WRONG — invents a page we read and found empty
Use the exported guards instead:
import CompetLab, { isMeasured, isMeasuredTrue, isMeasuredFalse } from '@competlab/sdk';
if (isMeasured(rival.facts)) {
console.log(`${rival.facts.length} facts read`); // narrowed to the list, no cast needed
} else {
console.log(`not read: ${rival.factsAvailable?.reason}`); // never_read or no_page
}
isMeasuredTrue and isMeasuredFalse do the same for a boolean | null: !value is also true
for null, so a bare negation reads "we didn't measure it" as "they don't have it".
Positioning reads the same way: a company's claims are null when the check did not measure them
(claimsAvailable.reason says why: never_read, no_page or not_judged), and an empty list is a homepage read that makes no claim the
check keeps. Card 2's empty column is an answer too: a claim of yours with an empty saidBy is one
nobody else makes on the homepages the check read — never call it unique.
const { data: pos } = await cl.positioning.dashboard('proj_abc'); // compact: each claim's kind and value
const rival = pos.item.companies.find((c) => !c.isSelf)!; // claims: PositioningClaimResponse[] | null
if (isMeasured(rival.claims)) {
const headline = rival.claims.find((claim) => claim.kind === 'headline');
console.log(`${rival.name ?? rival.domain} says '${headline?.value}'`); // the page's own words
} else {
console.log(`not read: ${rival.claimsAvailable?.reason}`); // never_read, no_page or not_judged
}
for (const claim of pos.item.yourClaims ?? []) {
console.log(claim.value, claim.saidBy.length === 0 ? '— nobody else says it on the homepages read' : claim.saidBy.map((s) => s.quote));
}
Two neighbours of null that are not null
An empty array is a measurement. null means we never looked; [] means we looked and there
was nothing there. programmaticExampleUrls is the clearest case — null exactly when
contentDataAvailable is present (no sitemap read, nothing to sample), [] when we read the
sitemap and the competitor genuinely publishes no templated pages.
An absent optional field is not a default. Fields added to a dimension only exist on runs
recorded after they shipped, so an older run omits them. trustComparisonState is the one to
watch: it tells you how to read trustSignalGap, and undefined means the state was never
computed — it does not mean 'compared'.
const summary = data.item.summary;
if (summary.trustComparisonState === undefined) {
// Pre-dates the field. You know the gap number, not whether it was a full comparison.
} else if (summary.trustComparisonState === 'some_competitors_unmeasured') {
// Incomplete: at least one competitor produced no usable check this run.
// A measured competitor may still be ahead — read the gap before describing it.
}
Error handling
Every method throws CompetLabError on failure — there is no error field on the result, so
data is always present when the call returns.
import CompetLab, { CompetLabError } from '@competlab/sdk';
try {
const { data } = await cl.projects.get('proj_abc');
console.log(data.item.name);
} catch (err) {
if (err instanceof CompetLabError) {
console.error(err.status, err.code, err.message); // 404 'project_not_found' '...'
if (err.code === 'rate_limit_exceeded') { /* back off and retry */ }
}
throw err;
}
code autocompletes to the documented values (api_key_invalid, project_not_found,
rate_limit_exceeded, …) while still accepting a code the API adds later. Failures that never
reached the API carry network_error (DNS, TLS, timeout) or http_error (a gateway or proxy
answered instead of the API).
API Reference
Full interactive API documentation with "Try It" panel:
Upgrading from v1.x
v2.0.0 is a breaking release. cl.analysis.actionPlan() was removed — the underlying API
endpoint no longer exists. Use the new Strategic Briefing, which synthesizes the same
competitive intelligence (and more):
// Before (v1.x):
const plan = await cl.analysis.actionPlan('proj_abc');
// After (v2.x):
const { data } = await cl.strategicBriefing.get('proj_abc');
// After (v6.x) — the recommendations are tickets on the board:
const recs = await cl.tickets.list('proj_abc', { origin: 'briefing' });
Full details in the CHANGELOG.
Requirements
- Node.js 20+
- CompetLab API key (start free trial — 14 days, no credit card)
Troubleshooting
Links
- REST API Reference
- MCP Server (AI-native access with 48 tools)
- GitHub — MCP Server
- Privacy Policy
- Start Free Trial
Support
- Bug reports: GitHub Issues
- Email: [email protected]
- Documentation: competlab.com/developers
License
MIT — see LICENSE
Built by the CompetLab team. Competitive intelligence for the AI era.