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

# Brand Monitor Analyses — List, Retrieve, Delete

> List all past brand analyses, retrieve a single analysis result by ID, or delete an analysis. All endpoints require a Bearer token and return JSON.

The analyses endpoints let you retrieve and manage the brand analyses stored in your CogNerd account. Use these endpoints to fetch historical results for your dashboard, build integrations that display visibility trends, or clean up analyses you no longer need. All endpoints require authentication and return standard JSON responses.

## List all analyses

Retrieves all past brand analyses for your authenticated account, ordered by most recent first.

### Endpoint

```
GET https://api.cognerd.in/api/brand-monitor/analyses
```

### Request headers

<ParamField header="Authorization" type="string" required>
  Your API token in the format `Bearer YOUR_TOKEN`.
</ParamField>

### Response

<ResponseField name="analyses" type="array">
  Array of analysis summary objects.

  <Expandable title="analysis summary fields">
    <ResponseField name="analyses[].id" type="string">
      Unique analysis identifier. Use this to fetch the full result or delete the analysis.
    </ResponseField>

    <ResponseField name="analyses[].brandName" type="string">
      The brand name that was analyzed.
    </ResponseField>

    <ResponseField name="analyses[].brandUrl" type="string">
      The brand URL that was analyzed, if one was provided.
    </ResponseField>

    <ResponseField name="analyses[].createdAt" type="string">
      ISO 8601 timestamp of when the analysis was created.
    </ResponseField>

    <ResponseField name="analyses[].visibilityScore" type="number">
      Overall AI visibility score from this analysis (0–100).
    </ResponseField>

    <ResponseField name="analyses[].status" type="string">
      Analysis status. One of `completed`, `interrupted`, or `failed`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Code examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cognerd.in/api/brand-monitor/analyses \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cognerd.in/api/brand-monitor/analyses', {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  });

  const { analyses } = await response.json();
  console.log(analyses);
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "analyses": [
    {
      "id": "ana_01j9z4k8m3f7c2x1v5b9n6p0q",
      "brandName": "Acme Corp",
      "brandUrl": "https://acmecorp.com",
      "createdAt": "2026-04-27T10:01:10.000Z",
      "visibilityScore": 67,
      "status": "completed"
    },
    {
      "id": "ana_01j9y2h5k8d4b3w7r1m9n4p2t",
      "brandName": "Acme Corp",
      "brandUrl": "https://acmecorp.com",
      "createdAt": "2026-04-20T09:15:42.000Z",
      "visibilityScore": 61,
      "status": "completed"
    }
  ]
}
```

***

## Get a single analysis

Retrieves the full analysis result for a specific analysis ID, including all visibility metrics, competitor data, platform breakdown, alerts, sources, and prompt analytics.

### Endpoint

```
GET https://api.cognerd.in/api/brand-monitor/analyses/:id
```

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the analysis to retrieve. Obtain this from the list analyses endpoint or from a previous `POST /analyze` result.
</ParamField>

### Request headers

<ParamField header="Authorization" type="string" required>
  Your API token in the format `Bearer YOUR_TOKEN`.
</ParamField>

### Response

The response contains the full analysis result object. The structure matches the `data` payload emitted in the final `result` SSE event from the [`POST /analyze`](/api/brand-monitor/analyze) endpoint.

<ResponseField name="id" type="string">
  Unique analysis identifier.
</ResponseField>

<ResponseField name="brandName" type="string">
  The brand name analyzed.
</ResponseField>

<ResponseField name="brandUrl" type="string">
  The brand URL analyzed, if provided.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the analysis was created.
</ResponseField>

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

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

        <ResponseField name="overview.mentions.explicit" type="number">
          Explicit brand mention count.
        </ResponseField>

        <ResponseField name="overview.mentions.implicit" type="number">
          Implicit brand reference count.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="overview.citations" type="object">
      <Expandable title="citation fields">
        <ResponseField name="overview.citations.total" type="number">
          Total source citation count.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

        <ResponseField name="overview.scores.averagePosition" type="number">
          Average position at which your brand appeared in AI answers.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="overview.opportunities" type="number">
      Number of prompts where a competitor appeared and your brand did not.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

    <ResponseField name="visibility.dailyTrend" type="array">
      Array of `{date, score}` objects for trend charting.
    </ResponseField>

    <ResponseField name="visibility.platformBreakdown" type="array">
      Per-platform breakdown. Each object includes `platform`, `score`, `mentions`, `citations`, `sentiment`, and `change`.
    </ResponseField>
  </Expandable>
</ResponseField>

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

  <Expandable title="competitors fields">
    <ResponseField name="competitors.competitors" type="array">
      Ranked list of competitors, including your own brand (`isOwn: true`). Each object includes `name`, `visibility`, `mentions`, `shareOfVoice`, `avgPos`, and `isOwn`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="alerts" type="object">
  Auto-generated alerts from this analysis run.

  <Expandable title="alerts fields">
    <ResponseField name="alerts.alerts" type="array">
      List of alert objects. Each includes `id`, `type`, `title`, `description`, and `time`. Alert types: `visibility_drop`, `visibility_spike`, `new_mention`, `competitor`, `sentiment`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sources" type="object">
  Source attribution mapping AI citations to specific pages.

  <Expandable title="sources fields">
    <ResponseField name="sources.sources" type="array">
      List of source objects. Each includes `domain`, `urls`, `mentions`, and `citations`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="prompts" type="object">
  Per-prompt analytics.

  <Expandable title="prompts fields">
    <ResponseField name="prompts.prompts" type="array">
      List of prompt analytics objects. Each includes `prompt`, `visibility`, `avgPosition`, and `trending`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="interruptedRun" type="boolean">
  `true` if this analysis was interrupted before it completed. Partial results may be present.
</ResponseField>

### Code examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cognerd.in/api/brand-monitor/analyses/ana_01j9z4k8m3f7c2x1v5b9n6p0q \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const id = 'ana_01j9z4k8m3f7c2x1v5b9n6p0q';

  const response = await fetch(
    `https://api.cognerd.in/api/brand-monitor/analyses/${id}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const analysis = await response.json();
  console.log('Visibility score:', analysis.visibility.score);
  console.log('Platform breakdown:', analysis.visibility.platformBreakdown);
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "id": "ana_01j9z4k8m3f7c2x1v5b9n6p0q",
  "brandName": "Acme Corp",
  "brandUrl": "https://acmecorp.com",
  "createdAt": "2026-04-27T10:01:10.000Z",
  "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
      }
    ]
  },
  "competitors": {
    "competitors": [
      {
        "name": "Acme Corp",
        "visibility": 67,
        "mentions": 12,
        "shareOfVoice": 38,
        "avgPos": 2.3,
        "isOwn": true
      },
      {
        "name": "Rival Co",
        "visibility": 74,
        "mentions": 15,
        "shareOfVoice": 47,
        "avgPos": 1.8,
        "isOwn": false
      }
    ]
  },
  "alerts": {
    "alerts": [
      {
        "id": "alert-1",
        "type": "visibility_spike",
        "title": "Visibility spike on ChatGPT",
        "description": "Your visibility on ChatGPT increased by 4 points since the last analysis.",
        "time": "just now"
      }
    ]
  },
  "sources": {
    "sources": [
      {
        "domain": "acmecorp.com",
        "urls": ["https://acmecorp.com/features", "https://acmecorp.com/pricing"],
        "mentions": 8,
        "citations": 3
      }
    ]
  },
  "prompts": {
    "prompts": [
      {
        "prompt": "What are the best project management tools for remote teams?",
        "visibility": 72,
        "avgPosition": 2,
        "trending": true
      }
    ]
  },
  "interruptedRun": false
}
```

### Error responses

| Status | Meaning                                                                     |
| ------ | --------------------------------------------------------------------------- |
| `401`  | Missing or invalid `Authorization` header.                                  |
| `404`  | No analysis with the given ID exists, or it belongs to a different account. |

***

## Delete an analysis

Permanently deletes an analysis from your account. This action cannot be undone.

### Endpoint

```
DELETE https://api.cognerd.in/api/brand-monitor/analyses/:id
```

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the analysis to delete.
</ParamField>

### Request headers

<ParamField header="Authorization" type="string" required>
  Your API token in the format `Bearer YOUR_TOKEN`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  `true` when the analysis was successfully deleted.
</ResponseField>

<ResponseField name="id" type="string">
  The ID of the deleted analysis.
</ResponseField>

### Code examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.cognerd.in/api/brand-monitor/analyses/ana_01j9z4k8m3f7c2x1v5b9n6p0q \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const id = 'ana_01j9z4k8m3f7c2x1v5b9n6p0q';

  const response = await fetch(
    `https://api.cognerd.in/api/brand-monitor/analyses/${id}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const result = await response.json();
  console.log(result.success); // true
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "success": true,
  "id": "ana_01j9z4k8m3f7c2x1v5b9n6p0q"
}
```

### Error responses

| Status | Meaning                                                                     |
| ------ | --------------------------------------------------------------------------- |
| `401`  | Missing or invalid `Authorization` header.                                  |
| `404`  | No analysis with the given ID exists, or it belongs to a different account. |