---
title: "Run an AI keyword discovery scan on a competitor"
method: POST
path: "/api/v1/competitors/{id}/scan"
tags: ["Write"]
---

# Run an AI keyword discovery scan on a competitor

`POST /api/v1/competitors/{id}/scan`

## Request

- Base URL: `https://api.trysonar.app`
- URL: `https://api.trysonar.app/api/v1/competitors/{id}/scan`
- Auth: HTTP bearer

Generates the search terms the competitor's listing is optimized for (brand terms included), queues them for SERP verification, and verifies the first batch inline (~30s); the rest verify in the background, recording both apps' ranks. Each org can scan a limited number of different competitors per UTC day (50 on trial and Indie, 250 on Agency); re-scanning a competitor already scanned today is free, and the background scan that runs when a competitor is added counts toward the same allowance. Requires an Indie or Agency plan and a write-scope API key.

## Path parameters

- `id` string, required

## Request body

- object
  - `own_app_id` string, uuid, required: Your own app the scan compares against

## Response `200`

Scan counts: { generated, queued, verified_now } — remaining candidates verify in the background; poll the competitor keywords endpoint for results

- object
  - `data` object, required: Result payload — full field reference at https://trysonar.app/docs/api

## Other responses

- `400`: Missing or invalid request parameters
- `401`: Missing or invalid API key
- `403`: Plan or scope insufficient (workspace endpoints need an Indie or Agency plan; writes also need a write-scope key)
- `404`: Resource not found or not tracked by your organization
- `429`: rate_limited — reason daily_scan_limit: the org's daily allowance of different competitors scanned is used up (limit, limit_unit competitors, reset_at = next 00:00 UTC, retry_after_seconds; Retry-After header). Keywords the competitor already ranks for stay readable via GET /api/v1/competitors/{id}/keywords. Or reason store_rate_limited: the store-scraper queue shed the work (transient).
- `500`: Unexpected server error

---

[API](https://skmtc.dev/trysonar/apis/sonar-api.md) · [All operations](https://skmtc.dev/trysonar/apis/sonar-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trysonar/apis/sonar-api/revisions/bf1d31dadd5f?raw)