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

Authorization

string

required

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

Content-Type

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

brandUrl

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.

brandName

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.

prompts

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

prompts[].id

string

Unique identifier for this prompt.

prompts[].prompt

string

required

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

prompts[].category

string

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

userSelectedCompetitors

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

userSelectedCompetitors[].name

string

Competitor brand name.

userSelectedCompetitors[].url

string

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

useWebSearch

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.

baseQuery

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

type

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.

data.overview

object

High-level mention and score summary.

Show overview fields

data.overview.mentions

object

Show mention fields

data.overview.mentions.total

number

Total brand mention count across all prompts and providers.

data.overview.mentions.explicit

number

Count of mentions where your brand name appeared explicitly.

data.overview.mentions.implicit

number

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

data.overview.citations

object

Show citation fields

data.overview.citations.total

number

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

data.overview.scores

object

Show score fields

data.overview.scores.visibilityScore

number

Overall AI visibility score from 0 to 100.

data.overview.scores.averagePosition

number

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

data.overview.opportunities

number

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

data.visibility

object

Detailed visibility metrics broken down by time and platform.

Show visibility fields

data.visibility.score

number

Overall AI visibility score (0–100).

data.visibility.dailyTrend

array

Array of daily score data points for trend charting.

Show dailyTrend item fields

data.visibility.dailyTrend[].date

string

ISO 8601 date string for this data point.

data.visibility.dailyTrend[].score

number

Visibility score on this date.

data.visibility.platformBreakdown

array

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

Show platform breakdown item fields

data.visibility.platformBreakdown[].platform

string

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

data.visibility.platformBreakdown[].score

number

Visibility score for this platform (0–100).

data.visibility.platformBreakdown[].mentions

number

Number of brand mentions on this platform.

data.visibility.platformBreakdown[].citations

number

Number of source citations on this platform.

data.visibility.platformBreakdown[].sentiment

string

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

data.visibility.platformBreakdown[].change

number

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

data.competitors

object

Competitor ranking data.

Show competitors fields

data.competitors.competitors

array

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

Show competitor item fields

data.competitors.competitors[].name

string

Competitor brand name.

data.competitors.competitors[].visibility

number

Competitor’s visibility score (0–100).

data.competitors.competitors[].mentions

number

Total mentions across all prompts and providers.

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

data.competitors.competitors[].avgPos

number

Average position at which this brand appears in AI answers.

data.competitors.competitors[].isOwn

boolean

true if this entry represents your own brand.

data.alerts

object

Automatically generated alerts based on analysis results.

Show alerts fields

data.alerts.alerts

array

List of alert objects.

Show alert item fields

data.alerts.alerts[].id

string

Unique alert identifier.

data.alerts.alerts[].type

string

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

data.alerts.alerts[].title

string

Short human-readable alert title.

data.alerts.alerts[].description

string

Detailed alert description explaining what triggered it.

data.alerts.alerts[].time

string

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

data.sources

object

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

Show sources fields

data.sources.sources

array

List of source attribution objects (up to 6).

Show source item fields

data.sources.sources[].domain

string

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

data.sources.sources[].urls

array

Specific page URLs cited by AI providers for this domain.

data.sources.sources[].mentions

number

Number of brand mentions associated with this source.

data.sources.sources[].citations

number

Number of times AI providers cited this source.

data.prompts

object

Analytics for each prompt used in the analysis.

Show prompts fields

data.prompts.prompts

array

List of prompt analytics objects (up to 6).

Show prompt analytics item fields

data.prompts.prompts[].prompt

string

The prompt text that was analyzed.

data.prompts.prompts[].visibility

number

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

data.prompts.prompts[].avgPosition

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.

data.interruptedRun

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"
  }'

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"}

Overview

Brand Monitor

GEO Assets

Content Studio

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)

Overview

Brand Monitor

GEO Assets

Content Studio

Documentation Index

​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)