POST /api/brand-monitor/analyze — Run Brand Analysis

The analyze endpoint runs CogNerd’s full brand intelligence pipeline against your brand and streams progress and results back in real time using Server-Sent Events (SSE). Each call costs 30 credits and is validated before the pipeline starts. The stream delivers incremental progress events as each stage completes, followed by a final result containing your AI visibility score, platform breakdown, competitor rankings, sentiment, alerts, source attribution, and prompt analytics.

This endpoint costs 30 credits per call. Your credit balance is checked before the pipeline starts. If you have fewer than 30 credits, the request is rejected with a 402 error and no credits are consumed.

This endpoint uses Server-Sent Events (SSE), not standard JSON. The response content type is text/event-stream. Use fetch with a streaming reader in JavaScript, or curl with --no-buffer in the terminal. Do not call this endpoint with a standard REST client expecting a JSON body.

Endpoint

POST https://api.cognerd.in/api/brand-monitor/analyze

Request headers

string

required

Your API token in the format Bearer YOUR_TOKEN. Obtain this from your CogNerd account settings.

string

required

Must be application/json.

string

Set to text/event-stream to receive SSE output. If omitted, most HTTP clients will still receive the stream but may buffer it.

Request body

string

The full URL of the brand to analyze, including scheme (e.g., https://yoursite.com). CogNerd scrapes this URL to extract brand metadata before running analysis. Provide either brandUrl or brandName, not both.

string

The brand name to analyze, used when you do not have a URL or want to analyze a brand by name only. CogNerd uses this name directly in prompt generation and scoring.

array

An optional array of pre-built prompt objects to use instead of auto-generated prompts. If omitted, CogNerd generates up to 4 prompts automatically based on your brand, industry, and competitors.

Show prompt object fields

string

Unique identifier for this prompt.

string

required

The text of the prompt to send to each AI provider.

string

Intent category for this prompt. Accepted values: organic_discovery, category_authority, competitive_evaluation, replacement_intent, conversational_recall, comparison, alternatives, recommendations.

array

An optional list of competitor brands to track. If provided, CogNerd uses this list instead of identifying competitors automatically via AI. Maximum 8 competitors.

Show competitor object fields

string

Competitor brand name.

string

Competitor website URL. Used to improve brand-detection accuracy when parsing AI responses.

boolean

default:"false"

When true, CogNerd runs each prompt through AI providers with live web search enabled (where the provider supports it). This produces more up-to-date results but may increase analysis time.

string

An optional seed query to prepend to the generated prompt list. Useful for anchoring the analysis around a specific question or topic relevant to your brand’s audience.

SSE event stream

The response is a stream of newline-delimited SSE events. Each event has the format:

data: {"type":"...","stage":"...","data":{...},"timestamp":"..."}

Events arrive in the following sequence as the pipeline progresses through its stages.

Pipeline stages

Stage	Description
`initializing`	Pipeline has started. Credit check passed.
`identifying-competitors`	CogNerd is identifying your competitors via AI or using your provided list.
`generating-prompts`	Prompts are being generated or validated.
`analyzing-prompts`	Each prompt is being sent to every configured AI provider.
`calculating-scores`	Visibility scores and competitor rankings are being computed.
`finalizing`	Analysis is complete. Final result is about to be emitted.

Event types

string

The type of SSE event. Possible values:

start — Pipeline has begun.
stage — A new pipeline stage has started. Includes stage name and progress (0–100).
progress — Progress update within a stage. Includes progress (0–100) and a human-readable message.
competitor-found — A competitor was identified. Includes competitor name, index, and total.
prompt-generated — A prompt was generated. Includes prompt text, category, index, and total.
prompt-dequeued — A prompt has started processing across all providers.
analysis-start — A specific provider has started analyzing a prompt.
analysis-complete — A specific provider finished analyzing a prompt. status is completed or failed.
partial-result — A provider returned a result for one prompt. Contains brandMentioned, brandPosition, and sentiment.
prompt-complete — All providers finished a prompt successfully.
prompt-failed — All or some providers failed for a prompt.
scoring-start — Competitor scoring has started for one competitor.
result — Final analysis result. Contains the full structured output described below.
error — A fatal error occurred and the stream is closing.

Final `result` event

When the pipeline finishes, a result event is emitted containing the complete analysis object.

object

High-level mention and score summary.

Show overview fields

object

Show mention fields

number

Total brand mention count across all prompts and providers.

number

Count of mentions where your brand name appeared explicitly.

number

Count of implicit references (e.g., via product names or URLs without the brand name).

object

Show citation fields

number

Total number of times your brand’s URLs or pages were cited as a source by AI providers.

object

Show score fields

number

Overall AI visibility score from 0 to 100.

number

Average position at which your brand appears in AI-generated answer lists (lower is better).

number

Number of prompts where a competitor appeared but your brand did not — representing gaps to close.

object

Detailed visibility metrics broken down by time and platform.

Show visibility fields

number

Overall AI visibility score (0–100).

array

Array of daily score data points for trend charting.

Show dailyTrend item fields

string

ISO 8601 date string for this data point.

number

Visibility score on this date.

array

Per-platform visibility metrics. One object per AI provider (e.g., ChatGPT, Claude, Gemini, Perplexity).

Show platform breakdown item fields

string

AI platform name (e.g., "ChatGPT", "Gemini", "Claude", "Perplexity").

number

Visibility score for this platform (0–100).

number

Number of brand mentions on this platform.

number

Number of source citations on this platform.

string

Dominant sentiment for your brand on this platform. One of positive, neutral, or negative.

number

Score change compared to the previous analysis run (positive or negative).

object

Competitor ranking data.

Show competitors fields

array

Ranked list of competitors (up to 8), including your own brand with isOwn: true.

Show competitor item fields

string

Competitor brand name.

number

Competitor’s visibility score (0–100).

number

Total mentions across all prompts and providers.

Percentage share of all AI mentions in this analysis (0–100).

number

Average position at which this brand appears in AI answers.

boolean

true if this entry represents your own brand.

object

Automatically generated alerts based on analysis results.

Show alerts fields

array

List of alert objects.

Show alert item fields

string

Unique alert identifier.

string

Alert type. One of: visibility_drop, visibility_spike, new_mention, competitor, sentiment.

string

Short human-readable alert title.

string

Detailed alert description explaining what triggered it.

string

Human-readable time label (e.g., "just now", "2 hours ago").

object

Source attribution data mapping AI citations back to specific pages on your site.

Show sources fields

array

List of source attribution objects (up to 6).

Show source item fields

string

Domain of the cited source (e.g., "yoursite.com").

array

Specific page URLs cited by AI providers for this domain.

number

Number of brand mentions associated with this source.

number

Number of times AI providers cited this source.

object

Analytics for each prompt used in the analysis.

Show prompts fields

array

List of prompt analytics objects (up to 6).

Show prompt analytics item fields

string

The prompt text that was analyzed.

number

Visibility score for your brand on this prompt (0–100).

number

Average position at which your brand appeared in responses to this prompt.

true if this prompt showed notable upward movement compared to prior analyses.

boolean

true if a previous analysis run was interrupted before completing. When present, the dashboard displays a recovery banner.

Error responses

Status	Meaning
`400`	Invalid or missing request body. Check that `brandUrl` or `brandName` is provided.
`401`	Missing or invalid `Authorization` header.
`402`	Insufficient credits. You need at least 30 credits to run an analysis.
`500`	Internal server error. The stream may emit an `error` event before closing.

Code examples

curl --no-buffer \
  --request POST \
  --url https://api.cognerd.in/api/brand-monitor/analyze \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/event-stream' \
  --data '{
    "brandUrl": "https://yoursite.com"
  }'

const response = await fetch('https://api.cognerd.in/api/brand-monitor/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({ brandUrl: 'https://yoursite.com' })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const event = JSON.parse(line.slice(6));

    if (event.type === 'result') {
      console.log('Visibility score:', event.data.visibility.score);
      console.log('Platform breakdown:', event.data.visibility.platformBreakdown);
    } else {
      console.log(`[${event.type}]`, event.data?.message || event.data);
    }
  }
}

Example SSE stream (truncated)

data: {"type":"start","stage":"initializing","data":{"stage":"initializing","progress":0,"message":"Starting analysis for Acme Corp"},"timestamp":"2026-04-27T10:00:00.000Z"}

data: {"type":"stage","stage":"identifying-competitors","data":{"stage":"identifying-competitors","progress":0,"message":"Identifying competitors..."},"timestamp":"2026-04-27T10:00:01.000Z"}

data: {"type":"competitor-found","stage":"identifying-competitors","data":{"competitor":"Rival Co","index":1,"total":3},"timestamp":"2026-04-27T10:00:03.000Z"}

data: {"type":"stage","stage":"generating-prompts","data":{"stage":"generating-prompts","progress":0,"message":"Generating analysis prompts..."},"timestamp":"2026-04-27T10:00:04.000Z"}

data: {"type":"prompt-generated","stage":"generating-prompts","data":{"prompt":"What are the best project management tools for remote teams?","category":"category_authority","index":1,"total":4},"timestamp":"2026-04-27T10:00:05.000Z"}

data: {"type":"partial-result","stage":"analyzing-prompts","data":{"provider":"ChatGPT","prompt":"...","response":{"provider":"ChatGPT","brandMentioned":true,"brandPosition":2,"sentiment":"positive"}},"timestamp":"2026-04-27T10:00:20.000Z"}

data: {"type":"result","stage":"finalizing","data":{"overview":{"mentions":{"total":12,"explicit":9,"implicit":3},"citations":{"total":5},"scores":{"visibilityScore":67,"averagePosition":2.3},"opportunities":4},"visibility":{"score":67,"dailyTrend":[{"date":"2026-04-27","score":67}],"platformBreakdown":[{"platform":"ChatGPT","score":72,"mentions":5,"citations":3,"sentiment":"positive","change":4},{"platform":"Gemini","score":61,"mentions":4,"citations":2,"sentiment":"neutral","change":-1}]},"alerts":{"alerts":[{"id":"alert-1","type":"visibility_spike","title":"Visibility spike on ChatGPT","description":"Your visibility on ChatGPT increased by 4 points.","time":"just now"}]},"sources":{"sources":[{"domain":"yoursite.com","urls":["https://yoursite.com/features"],"mentions":8,"citations":3}]},"prompts":{"prompts":[{"prompt":"What are the best project management tools?","visibility":72,"avgPosition":2,"trending":true}]}},"timestamp":"2026-04-27T10:01:10.000Z"}

Get Started

Dashboard

Guides

Credits & Plans

Help

POST /api/brand-monitor/analyze — Run Brand Analysis

Endpoint

Request headers

Request body

SSE event stream

Pipeline stages

Event types

Final `result` event

Error responses

Code examples

Example SSE stream (truncated)

​Endpoint

​Request headers

​Request body

​SSE event stream

​Pipeline stages

​Event types

​Final result event

​Error responses

​Code examples

​Example SSE stream (truncated)

Endpoint

Request headers

Request body

SSE event stream

Pipeline stages

Event types

Final `result` event

Error responses

Code examples

Example SSE stream (truncated)