---
title: "List competitor suggestions"
method: GET
path: "/competitors/suggestions"
tags: ["Competitors"]
---

# List competitor suggestions

`GET /competitors/suggestions`

## Request

- Base URL: `https://api.llmpulse.ai/api/v1`
- URL: `https://api.llmpulse.ai/api/v1/competitors/suggestions`
- Auth: API key in header `Authorization`

The two lists of the Suggested tab of the Competitors page. `basis=brands` (default) returns the competing brands the AI discovery proposed that are not tracked or rejected yet, with the names it would match and, when counted, how many answers name it (`mentions`). `basis=citations` returns the domains AI answers cite most that are not your own or tracked yet, with how many answers cite each (`citations`). `discovery` tells whether a discovery run is still loading. Read-only: it never starts a discovery run, which the page starts from its Discover button. Add a suggestion with POST /competitors.

## Query parameters

- `project_id` integer, required
- `basis` 'brands' | 'citations'
- `query` string
- `page` integer
- `per_page` integer
- `output` 'flat' | 'csv'

## Response `200`

Paginated suggestions

- CompetitorSuggestionsResponse: Envelope shared by the paginated listings; each listing adds its own data rows
  - `project_id` integer, required
  - `page` integer, required
  - `per_page` integer, required
  - `total` integer, required: Rows matching the filters across every page
  - `request_id` string, required
  - `basis` 'brands' | 'citations', required
  - `discovery` CompetitorDiscoveryState, required
    - `status` string, nullable: The last discovery run: pending, processing, completed or failed; null when none ever ran
    - `loading` boolean, required: A discovery run is in progress
    - `generated_at` string, date-time, nullable
  - `data` CompetitorSuggestion[], required
    - `id` string, required: The suggestion key (brands) or the id of one citing source row (citations)
    - `domain` string, required
    - `brand_name` string, nullable: The proposed brand name; null for a cited domain
    - `matching_names` string[], required: The names a tracked competitor would be matched by; empty for a cited domain
    - `mentions` integer, nullable: Answers naming the brand, when the discovery counted them (brands only)
    - `citations` integer, nullable: Answers citing the domain (citations only)

## Other responses

- `422`: Invalid parameters

## Changes

- **2026-10-16** `dd090b1e1154`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/llmpulse/apis/llm-pulse-api/changes/competitors/suggestions/get.md)

---

[API](https://skmtc.dev/llmpulse/apis/llm-pulse-api.md) - [All operations](https://skmtc.dev/llmpulse/apis/llm-pulse-api/llms.txt) - [OpenAPI document](https://skmtc.dev/llmpulse/apis/llm-pulse-api/revisions/38a31f123641?raw)