---
title: Discover Competitors
api: POST /brands/{brand_id}/discover-competitors
description: "Automatically discover competitors in your space using JTBD-framed research."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

Uses Tavily research to find business, SERP, and content competitors for your brand. Competitors are classified by type and tier.

**Duration:** 2-5 minutes.

## Path parameters

<ParamField path="brand_id" type="string" required>
  The brand UUID.
</ParamField>

## Query parameters

<ParamField query="persist" type="boolean" default="true">
  Whether to save the discovered competitors to the brand record. Set to `false` to preview results without mutating the brand. **This is a query parameter, not a request body field** — pass it as `?persist=false` on the URL.
</ParamField>

## Response (202 Accepted)

```json
{
  "run_id": "run-uuid",
  "status": "queued"
}
```

Discovered competitors are added to the brand's competitor list (when `persist=true`, the default). View them via `GET /brands/{id}`.

## Errors

| Status | Meaning |
|---|---|
| `404` | Brand not found, or not owned by the caller. |
| `409` | Returned when **(a)** another `competitor_discovery` run is already active for this brand, or **(b)** a `full` (`/analyze`) run is currently writing to all tables. Other partial runs do **not** block this endpoint. Header: `X-Running-Run-Id`. Active runs older than 15 minutes are auto-expired and do not count. |
| `422` | `brand_id` is not a valid UUID. |

## Example

```bash
# Persist to brand (default)
curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  https://api.boringmarketing.com/brands/$BRAND_ID/discover-competitors

# Preview without mutating the brand
curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/brands/$BRAND_ID/discover-competitors?persist=false"
```

<Tip>
The full pipeline (`/analyze`) triggers competitor discovery automatically if no competitors are set. Use this endpoint when you want to refresh competitors independently.
</Tip>