---
title: "Discovered keywords for an app (what to track next)"
method: GET
path: "/api/v1/apps/{id}/discovered-keywords"
tags: ["Workspace"]
---

# Discovered keywords for an app (what to track next)

`GET /api/v1/apps/{id}/discovered-keywords`

## Request

- Base URL: `https://api.trysonar.app`
- URL: `https://api.trysonar.app/api/v1/apps/{id}/discovered-keywords`
- Auth: HTTP bearer

Keywords Sonar's discovery engine surfaced for the app but that aren't tracked yet — ranked finds (bucket `ranked`), competitor gaps (`gap`), and idea suggestions (`idea`) — each with latest metrics, AI relevance (0-100), and an opportunity score (0-100). Sorted by opportunity, best first; `total` is the filtered count before `limit`. Track the winners via POST /api/v1/apps/{id}/keywords. Requires an Indie or Agency plan. Keyword rows carry `popularity`, `popularity_source`, `popularity_apple` and `popularity_proxy` — the same values the dashboard shows (see the PopularityFields schema).

## Path parameters

- `id` string, required

## Query parameters

- `country` string
- `source` 'autocomplete' | 'metadata' | 'serp_scan' | 'competitor' | 'apple_ads' | 'ai'
- `status` 'new' | 'tracked' | 'hidden' | 'all'
- `bucket` 'ranked' | 'gap' | 'idea'
- `min_relevance` integer
- `min_opportunity` integer
- `limit` integer

## Response `200`

{ app_id, total, keywords: [{ id, keyword_id, keyword, store, country, rank, source, status, bucket, popularity, popularity_source, popularity_apple, popularity_proxy, difficulty, ai_relevance, opportunity, discovered_at, ranks_checked_at }] }

- 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 — see `error.reason`: daily_limit (Indie 1,000, Agency 5,000, trial 150 requests/day, resets 00:00 UTC; see `reset_at`), anonymous_daily_limit / batch_too_large (keyless free tier), store_rate_limited or concurrency_limit (transient, honor `retry_after_seconds`)
- `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)