---
title: "Suggest competitors"
method: POST
path: "/org/competitors/suggest"
tags: ["Tracked Competitors"]
---

# Suggest competitors

`POST /org/competitors/suggest`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/competitors/suggest`
- Auth: API key in header `X-API-Key`

Generates AI competitor suggestions seeded from your organization's recent prompt-run text or a web search. Takes no request body.

## Response `200`

The generated suggestions.

- SuggestCompetitorsResponse: AI-generated competitor suggestions for your organization.
  - `mode` string, required: Which suggestion mode ran — `run_text` (from recent prompt-run text) or `web_search`.
  - `suggestions` CompetitorSuggestion[], required
    - `name` string, required: Suggested competitor brand name.
    - `url` string: Suggested competitor website URL, when found.
    - `source` 'suggested_run_text' | 'suggested_web_search', required: Which suggestion mode produced this — from prompt-run text or a web search.
    - `confidence` number, required: Suggestion confidence (0–1).
    - `rationale` string, required: Why this competitor was proposed.
    - `already_tracked` boolean, required: True when an active competitor with the same name is already tracked.
  - `sampled_run_ids` string[]: Prompt-run ids sampled to produce the suggestions (run_text mode).
  - `duration_ms` integer, required: How long the suggestion run took, in milliseconds.
  - `cached` boolean, required: Whether the result was served from cache.

## Other responses

- `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header.
- `422`: The request was well-formed but cannot be fulfilled given the current state (e.g. insufficient data to act on).
- `429`: Rate limit exceeded — retry later.
- `503`: The service is temporarily unavailable — retry later.

---

[API](https://skmtc.dev/senso/apis/senso-org-api.md) - [All operations](https://skmtc.dev/senso/apis/senso-org-api/llms.txt) - [OpenAPI document](https://skmtc.dev/senso/apis/senso-org-api/revisions/d789b4fcbe84?raw)