> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognerd.in/llms.txt
> Use this file to discover all available pages before exploring further.

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

> POST /api/brand-monitor/analyze — streams a real-time brand analysis via SSE. Returns visibility score, platform breakdown, sentiment, and competitor data.

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.

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

## Endpoint

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

## Request headers

<ParamField header="Authorization" type="string" required>
  Your API token in the format `Bearer YOUR_TOKEN`. Obtain this from your CogNerd account settings.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="Accept" type="string">
  Set to `text/event-stream` to receive SSE output. If omitted, most HTTP clients will still receive the stream but may buffer it.
</ParamField>

## Request body

<ParamField body="brandUrl" type="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.
</ParamField>

<ParamField body="brandName" type="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.
</ParamField>

<ParamField body="prompts" type="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.

  <Expandable title="prompt object fields">
    <ParamField body="prompts[].id" type="string">
      Unique identifier for this prompt.
    </ParamField>

    <ParamField body="prompts[].prompt" type="string" required>
      The text of the prompt to send to each AI provider.
    </ParamField>

    <ParamField body="prompts[].category" type="string">
      Intent category for this prompt. Accepted values: `organic_discovery`, `category_authority`, `competitive_evaluation`, `replacement_intent`, `conversational_recall`, `comparison`, `alternatives`, `recommendations`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="userSelectedCompetitors" type="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.

  <Expandable title="competitor object fields">
    <ParamField body="userSelectedCompetitors[].name" type="string">
      Competitor brand name.
    </ParamField>

    <ParamField body="userSelectedCompetitors[].url" type="string">
      Competitor website URL. Used to improve brand-detection accuracy when parsing AI responses.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="useWebSearch" type="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.
</ParamField>

<ParamField body="baseQuery" type="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.
</ParamField>

## 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

<ResponseField name="type" 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.
</ResponseField>

### Final `result` event

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

<ResponseField name="data.overview" type="object">
  High-level mention and score summary.

  <Expandable title="overview fields">
    <ResponseField name="data.overview.mentions" type="object">
      <Expandable title="mention fields">
        <ResponseField name="data.overview.mentions.total" type="number">
          Total brand mention count across all prompts and providers.
        </ResponseField>

        <ResponseField name="data.overview.mentions.explicit" type="number">
          Count of mentions where your brand name appeared explicitly.
        </ResponseField>

        <ResponseField name="data.overview.mentions.implicit" type="number">
          Count of implicit references (e.g., via product names or URLs without the brand name).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="data.overview.citations" type="object">
      <Expandable title="citation fields">
        <ResponseField name="data.overview.citations.total" type="number">
          Total number of times your brand's URLs or pages were cited as a source by AI providers.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="data.overview.scores" type="object">
      <Expandable title="score fields">
        <ResponseField name="data.overview.scores.visibilityScore" type="number">
          Overall AI visibility score from 0 to 100.
        </ResponseField>

        <ResponseField name="data.overview.scores.averagePosition" type="number">
          Average position at which your brand appears in AI-generated answer lists (lower is better).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="data.overview.opportunities" type="number">
      Number of prompts where a competitor appeared but your brand did not — representing gaps to close.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.visibility" type="object">
  Detailed visibility metrics broken down by time and platform.

  <Expandable title="visibility fields">
    <ResponseField name="data.visibility.score" type="number">
      Overall AI visibility score (0–100).
    </ResponseField>

    <ResponseField name="data.visibility.dailyTrend" type="array">
      Array of daily score data points for trend charting.

      <Expandable title="dailyTrend item fields">
        <ResponseField name="data.visibility.dailyTrend[].date" type="string">
          ISO 8601 date string for this data point.
        </ResponseField>

        <ResponseField name="data.visibility.dailyTrend[].score" type="number">
          Visibility score on this date.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="data.visibility.platformBreakdown" type="array">
      Per-platform visibility metrics. One object per AI provider (e.g., ChatGPT, Claude, Gemini, Perplexity).

      <Expandable title="platform breakdown item fields">
        <ResponseField name="data.visibility.platformBreakdown[].platform" type="string">
          AI platform name (e.g., `"ChatGPT"`, `"Gemini"`, `"Claude"`, `"Perplexity"`).
        </ResponseField>

        <ResponseField name="data.visibility.platformBreakdown[].score" type="number">
          Visibility score for this platform (0–100).
        </ResponseField>

        <ResponseField name="data.visibility.platformBreakdown[].mentions" type="number">
          Number of brand mentions on this platform.
        </ResponseField>

        <ResponseField name="data.visibility.platformBreakdown[].citations" type="number">
          Number of source citations on this platform.
        </ResponseField>

        <ResponseField name="data.visibility.platformBreakdown[].sentiment" type="string">
          Dominant sentiment for your brand on this platform. One of `positive`, `neutral`, or `negative`.
        </ResponseField>

        <ResponseField name="data.visibility.platformBreakdown[].change" type="number">
          Score change compared to the previous analysis run (positive or negative).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.competitors" type="object">
  Competitor ranking data.

  <Expandable title="competitors fields">
    <ResponseField name="data.competitors.competitors" type="array">
      Ranked list of competitors (up to 8), including your own brand with `isOwn: true`.

      <Expandable title="competitor item fields">
        <ResponseField name="data.competitors.competitors[].name" type="string">
          Competitor brand name.
        </ResponseField>

        <ResponseField name="data.competitors.competitors[].visibility" type="number">
          Competitor's visibility score (0–100).
        </ResponseField>

        <ResponseField name="data.competitors.competitors[].mentions" type="number">
          Total mentions across all prompts and providers.
        </ResponseField>

        <ResponseField name="data.competitors.competitors[].shareOfVoice" type="number">
          Percentage share of all AI mentions in this analysis (0–100).
        </ResponseField>

        <ResponseField name="data.competitors.competitors[].avgPos" type="number">
          Average position at which this brand appears in AI answers.
        </ResponseField>

        <ResponseField name="data.competitors.competitors[].isOwn" type="boolean">
          `true` if this entry represents your own brand.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.alerts" type="object">
  Automatically generated alerts based on analysis results.

  <Expandable title="alerts fields">
    <ResponseField name="data.alerts.alerts" type="array">
      List of alert objects.

      <Expandable title="alert item fields">
        <ResponseField name="data.alerts.alerts[].id" type="string">
          Unique alert identifier.
        </ResponseField>

        <ResponseField name="data.alerts.alerts[].type" type="string">
          Alert type. One of: `visibility_drop`, `visibility_spike`, `new_mention`, `competitor`, `sentiment`.
        </ResponseField>

        <ResponseField name="data.alerts.alerts[].title" type="string">
          Short human-readable alert title.
        </ResponseField>

        <ResponseField name="data.alerts.alerts[].description" type="string">
          Detailed alert description explaining what triggered it.
        </ResponseField>

        <ResponseField name="data.alerts.alerts[].time" type="string">
          Human-readable time label (e.g., `"just now"`, `"2 hours ago"`).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.sources" type="object">
  Source attribution data mapping AI citations back to specific pages on your site.

  <Expandable title="sources fields">
    <ResponseField name="data.sources.sources" type="array">
      List of source attribution objects (up to 6).

      <Expandable title="source item fields">
        <ResponseField name="data.sources.sources[].domain" type="string">
          Domain of the cited source (e.g., `"yoursite.com"`).
        </ResponseField>

        <ResponseField name="data.sources.sources[].urls" type="array">
          Specific page URLs cited by AI providers for this domain.
        </ResponseField>

        <ResponseField name="data.sources.sources[].mentions" type="number">
          Number of brand mentions associated with this source.
        </ResponseField>

        <ResponseField name="data.sources.sources[].citations" type="number">
          Number of times AI providers cited this source.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.prompts" type="object">
  Analytics for each prompt used in the analysis.

  <Expandable title="prompts fields">
    <ResponseField name="data.prompts.prompts" type="array">
      List of prompt analytics objects (up to 6).

      <Expandable title="prompt analytics item fields">
        <ResponseField name="data.prompts.prompts[].prompt" type="string">
          The prompt text that was analyzed.
        </ResponseField>

        <ResponseField name="data.prompts.prompts[].visibility" type="number">
          Visibility score for your brand on this prompt (0–100).
        </ResponseField>

        <ResponseField name="data.prompts.prompts[].avgPosition" type="number">
          Average position at which your brand appeared in responses to this prompt.
        </ResponseField>

        <ResponseField name="data.prompts.prompts[].trending" type="boolean">
          `true` if this prompt showed notable upward movement compared to prior analyses.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.interruptedRun" type="boolean">
  `true` if a previous analysis run was interrupted before completing. When present, the dashboard displays a recovery banner.
</ResponseField>

## 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
      }
    }
  }
  ```
</CodeGroup>

### Example SSE stream (truncated)

```text theme={null}
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"}
```