---
title: "Ai Search Competitors"
method: POST
path: "/api/v1/brand-library/ai-search-competitors"
tags: ["Brand Library (Tech Spike)"]
---

# Ai Search Competitors

`POST /api/v1/brand-library/ai-search-competitors`

## Request

- Base URL: `https://geo.sig.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://geo.sig.ai/api/v1/brand-library/ai-search-competitors`
- Auth: none declared

AI-powered competitor search using Bedrock Claude + Tavily.

**Cache-First Architecture Enhancement**

This endpoint searches for competitors using AI when cache is empty or stale.
Results are automatically cached for fast subsequent queries.

**How It Works:**
1. Uses Tavily to search web for "{vertical} companies 2024 2025"
2. Claude Sonnet 4 extracts structured competitor list
3. Results are cached in brand_library table
4. Next query for same vertical returns cached results instantly

**Example Request:**
```
POST /api/v1/brand-library/ai-search-competitors?vertical=Agriculture%20Tech&limit=15
```

**Example Response:**
```json
{
  "vertical": "Agriculture Tech",
  "count": 15,
  "total_brands": 15,
  "suggestions": [
    {
      "brand": "John Deere",
      "tier": "Leader",
      "rank": 1,
      "confidence": "High",
      "signal": "Leading precision agriculture with autonomous tractors in 2024",
      "is_parent": false,
      "products": []
    },
    ...
  ]
}
```

**Args:**
- `vertical`: Industry vertical to search (e.g., "Agriculture Tech")
- `limit`: Max competitors to find (1-50, default 15)
- `cache_results`: Whether to save results to database (default true)

**Returns:**
- List of AI-discovered competitors with metadata

**Status Codes:**
- 200: Success (may take 3-10 seconds for AI search, returns empty list if Tavily API fails)
- 500: AI search failed (check logs)

**Performance:**
- First query: 3-10 seconds (AI search + web scraping)
- Cached queries: <100ms (instant from database)

**Fallback Behavior:**
- If Tavily API is unavailable (quota exceeded, rate limit, network error), returns empty results
- Clients should fall back to cached data from /suggest-competitors endpoint
- Graceful degradation: no errors exposed to end users, just empty competitor list
- Tavily API errors logged as WARNING for monitoring

## Query parameters

- `vertical` string, required: Vertical/industry to search for competitors
- `limit` integer: Maximum number of competitors to find
- `cache_results` boolean: Whether to cache results in brand library

## Response `200`

Successful Response

- CompetitorSuggestionsResponse: Response model for competitor suggestions endpoint.
  - `vertical` string, required
  - `count` integer, required
  - `total_brands` integer, required
  - `suggestions` GroupedBrandSuggestion[], required
    - `id` string, uuid, required
    - `brand` string, required
    - `website` string, required
    - `vertical` string, required
    - `subcategory` string, required
    - `tier` string, required
    - `rank` integer, nullable, required
    - `confidence` string, required
    - `signal` string, nullable, required
    - `is_parent` boolean
    - `products` BrandProduct[]
      - `id` string, uuid, required
      - `product_name` string, required
      - `full_name` string, required
      - `website` string, required
      - `subcategory` string, required
      - `tier` string, required
      - `rank` integer, nullable, required
      - `confidence` string, required
      - `signal` string, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api.md) · [All operations](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/revisions/3ec39f9be9e0?raw)