app.trysonar/sonar

The cached AI analysis of an ad (hook, angle, format, structure, CTA, why it works) and its video transcript, or `analysis: null` when it hasn't been analyzed yet — then use sonar_ad_spy_analyze_ad. Free cached read. Requires an Indie or Agency plan (a trial counts).

A Facebook page's cached Meta ads (Facebook, Instagram, Messenger, Audience Network): stats over every cached ad (active count, longest running, new in 30 days, format and placement mix, max variants), the ads matching the filters with copy, CTA, landing URL, placements, days running and a longevity tier (30d+/60d+/90d+), and daily history of active/new ads (creative velocity). No spend or impression data exists for ads outside the EU — longevity and variants are the signals. Compact by default (no expiring media links; fields: "full" adds them). Media URLs are expiring CDN links; always give users each ad's permanent `library_url`. `refresh_due: true` means the copy is over 24h old (sonar_ad_spy_refresh fetches it). Cached read. Requires an Indie or Agency plan (a trial counts).

WRITE tool — AI breakdown of why an ad works: hook, persuasion angle, creative format, beat-by-beat structure, CTA and a grounded "why it works" (no invented metrics). Analyses are cached for every Sonar account: an ad that already has one comes back free (`cached: true`), otherwise the first analysis spends one of the account's daily Ad Spy lookups (a video transcript plus one AI call). Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

Start here for competitor ads. Every competitor the account tracks, with the Facebook pages (meta_pages) and TikTok accounts (tiktok_accounts) already linked to it and its last page scan, plus today's Ad Spy lookup allowance (used / limit / remaining / resets_at). A competitor with no linked page needs sonar_ad_spy_scan then sonar_ad_spy_link. Cached read. Requires an Indie or Agency plan (a trial counts).

WRITE tool — remove irrelevant ads from this account's scans ("Remove from scan"), or put them back with hidden: false. Per account only; other accounts still see them. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — confirm which Facebook page or TikTok account belongs to a competitor. Only call it after the user picked the candidate (the mapping is shared by every Sonar account). Accepts only candidates this account's own scans or searches returned in the last 2 days. Spends no lookup; then use sonar_ad_spy_refresh to fetch the ads. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — open a Facebook page from a recent search or scan without linking it to a competitor, and return its ads (same shape and filters as sonar_ad_spy_ads). The ads are fetched when the cached copy is over 24h old. Spends one of the account's daily Ad Spy lookups (today's usage comes back in `allowance` from sonar_ad_spy_competitors); re-opening the same page, account or ad the same day is free. Past the allowance a refresh returns the cached copy with `meta.stale` and a `meta.note` to relay. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — fetch a page's current Meta ads or a TikTok account's latest videos when the cached copy is over 24h old (a fresher copy comes back unchanged and costs nothing). Linked pages also refresh weekly on their own. Returns the same view as sonar_ad_spy_ads / sonar_ad_spy_tiktok_posts. Spends one of the account's daily Ad Spy lookups (today's usage comes back in `allowance` from sonar_ad_spy_competitors); re-opening the same page, account or ad the same day is free. Past the allowance a refresh returns the cached copy with `meta.stale` and a `meta.note` to relay. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — search a competitor's Facebook page (channel "meta") or TikTok account (channel "tiktok") and return ranked candidates; an unambiguous top match is flagged `best_match`. It never links: show the candidates and let the user confirm, then call sonar_ad_spy_link (the page mapping is shared by every Sonar account, so a wrong link misleads everyone). A Meta scan that found nothing in the last 24h replays for free (`cooldown: true`). Spends one of the account's daily Ad Spy lookups (today's usage comes back in `allowance` from sonar_ad_spy_competitors); re-opening the same page, account or ad the same day is free. Past the allowance a refresh returns the cached copy with `meta.stale` and a `meta.note` to relay. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — adapt a proven competitor ad's FORMAT (not its claims or brand) into an organic TikTok or Reels script the user can film: hook, beats (shot + on-screen text), soft CTA, audio and caption ideas. Every call is a new AI generation and spends one of the account's daily Ad Spy lookups (plus one for the ad's first analysis when it has none yet). Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — free-text search for Facebook advertiser pages by brand or company name, not tied to a tracked competitor. Open a result with sonar_ad_spy_open_page, or link it to a competitor with sonar_ad_spy_link. Spends one of the account's daily Ad Spy lookups (today's usage comes back in `allowance` from sonar_ad_spy_competitors); re-opening the same page, account or ad the same day is free. Past the allowance a refresh returns the cached copy with `meta.stale` and a `meta.note` to relay. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

A linked TikTok account's cached public videos with real counters (views, likes, comments, shares, saves), caption, post date and a `breakout` flag (3× or more the account's median views). Use `url` (permanent); compact by default, so the expiring `cover_url` is left out (fields: "full" adds it). Cached read; sonar_ad_spy_refresh with kind "tiktok" fetches newer videos. Requires an Indie or Agency plan (a trial counts).

WRITE tool — remove a wrong competitor → Facebook page (advertiser_id) or TikTok account (account_id) link. Pass exactly one. The link is shared, so this also removes it for other Sonar accounts tracking that competitor. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

The account's saved ads (the vault), newest first: details frozen at save time, status (pending/stored/partial/failed), notes and stored media files, plus usage vs the plan's vault limit. Asset URLs need the account's API key — vault media is private, never share them as public links. Requires an Indie or Agency plan (a trial counts).

WRITE tool — delete a saved ad and its stored media files from the vault. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — save Meta ads to the account's private vault: details are frozen and the media downloaded into Sonar's storage, so the ad survives being stopped or its links expiring. Saves what fits the plan's vault limit and reports the rest as `over_limit`; poll sonar_ad_spy_vault for status. An ad whose media links already expired is refetched once, which spends one Ad Spy lookup. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — set or clear a saved ad's note and/or retry its media download. Requires an Indie or Agency plan (a trial counts) and an authorized Sonar account or an API key with the write scope.

Append a screen to a screenshot set (at the end; reorder with sonar_update_screenshot_set). Requires an Indie plan (trial counts) and an authorized Sonar account or a write-scope API key.

The detected alert events for your workspace, newest first — the same feed as the in-app Recent Alerts panel and the email digest: rank drops/gains, top-10 entries/exits, new rankings, rating drops, review spikes, and competitor changes, each with a type-specific payload (app/keyword names, old vs new values). Events only exist for alert types you've enabled rules for (sonar_set_alert); detection runs once daily. Poll with `since` to react to changes programmatically. Requires an Indie plan (trial counts).

WRITE tool — generates a fresh AI competitive insight for one of your own apps: clusters the keyword gaps vs your competitors into named opportunity themes (with a why-now narrative and per-keyword metrics), writes threat narratives for competitors climbing on your keywords, and diffs against the previous analysis. At most one analysis per app per 7 days (429 with the next available time while in cooldown — use sonar_competitor_landscape to read the current one). Requires a paid (non-trial) Indie plan and an authorized Sonar account or an API key with the write scope.

Calculate an ASO (App Store Optimization) audit score (0-100) for an app. Returns the overall score plus an itemized breakdown of checks (title length, keyword usage, screenshots, ratings, etc.) so you can identify what to improve. Works without an API key (free tier, limited daily use per IP).

Change history for a tracked app — detected releases, metadata edits, screenshot swaps, price changes, category moves, iOS product page header swaps (`header`: data.action added/changed/removed + header artwork) and newly listed iOS In-App Events (`in_app_event`: title, kind, dates), newest first. Useful for correlating rank movements with what the app (or a competitor) changed. Requires an Indie plan (trial counts).

App Store Connect App Analytics for one of your own iOS apps: the impressions → product page views → downloads funnel with conversion rates (`page_view_rate`, `download_rate`) and App Store search share, impressions by source (App Store search, browse, app referrer, web referrer…), plus daily installs, deletions and sessions. Impressions follow App Store Connect's definition and INCLUDE product page views, so totals reconcile with ASC. Downloads come from the Sales report. Same numbers as the Engagement page. iOS only. Requires the Agency plan (403 on other plans) AND an App Store Connect connection with an Admin-role key (`key_lacks_analytics` otherwise); Apple delivers the first analytics 24-48 hours after connecting (`pending`). Always check `status`: anything other than `ready` (not_connected, not_ios, app_not_in_account, pending, key_lacks_analytics) means there's no data and `message` says how to fix it — never read an empty series as zero. Days Apple hasn't reported yet have `reported: false` and null metrics.

Extract the most likely target keywords from an app's title and description, ranked by relevance. Useful for understanding what an app (yours or a competitor) is optimizing for. Works without an API key (free tier, limited daily use per IP).

List the keywords tracked for an app in the caller's Sonar workspace, with latest difficulty, popularity, results count, note, and starred_at (favorite/target marker) per keyword. Returns the tracked-keyword ids used by sonar_update_keyword_note and sonar_star_keyword, and the keyword_ids used by sonar_keyword_rankings. Cursor-paginated (default 50 per page). Requires an Indie plan (trial counts). `popularity` (5-100) is the value Sonar's dashboard shows: Apple's Search Popularity when Apple has a real reading; when Apple reports a keyword below its threshold (popularity_apple 5, about 20) it is Sonar's estimate (at most 18). `popularity_source` says which (apple | proxy), `popularity_apple` is Apple's own reading (null on Android), `popularity_proxy` is Sonar's estimate beside a floored reading.

Look up a single app by its store ID. Returns app metadata including name, developer, category, rating, reviews, installs (Android), and price. Works without an API key (free tier, limited daily use per IP). If the store is throttling, the result may be Sonar's stored copy: it then comes back as `{ data, meta }` with `meta.stale: true`, its date in `meta.stale_as_of`, and a `meta.note` to pass on to the user.

The dashboard's computed scoreboard for one of your apps in a single call: visibility index and share of voice (with 7-day deltas and a daily spark), ranked / top-10 keyword counts with movement, best rank, the biggest 7-day improvements and drops, the rank-distribution trend, and the actionable opportunity list (near_page_one / top_three_push / easy_target). Use it when asked how an app is doing: these are the same numbers the dashboard renders, already computed from rank history. Requires an Indie plan (trial counts).

Rank history for an app's tracked keywords over the requested window. Compact by default: each keyword's current rank and status, best rank, positions gained and a newest-first daily `ranks` list (a rank, "unranked" = checked but not found, null = no check that day). Pass fields: "full" for the per-day `observations` grid: ranked has a numeric rank; not_found means a completed search did not return the app (results_count is the returned search size); not_observed means no confirmed check, including legacy gaps. Never interpret an absent rank as a collection failure or assign a numeric rank to it. The legacy history array contains positive ranks only. Use this to check how rankings moved after a metadata change or to find keywords trending up or down. Cursor-paginated over keywords (default 50 per page). Requires an Indie plan (trial counts).

Estimate monthly revenue for an app, based on install counts, ratings, and category benchmarks. Returns the dollar estimate with its likely range (`monthly_range`), the install base it rests on (`installs`: estimate, low, high, source), a confidence grade (high/medium/low) with the factors behind it, and the methodology used. On the App Store installs aren't public: they are estimated from that storefront's rating count (`source: review_derived`), apps differ several-fold in installs per rating, so quote the range rather than the point figure — those estimates are never graded above medium. Google Play's public install count (`source: public_install_count`) has no install range. The figure is a model estimate, not reported revenue. Needs a Sonar API key or connected account (1 credit per call on prepaid API credits); not part of the free tier.

Fetch user reviews for any app, live from the store (up to ~500 of the most recent or most helpful for the country). The star-rating filters and `limit` apply to that fetched window, so a narrow filter on a small app can return few or no reviews. Useful for sentiment analysis, feature-request mining, and competitive research; for an already-summarized view of a tracked app, sonar_review_insights returns themed AI analysis instead. Needs a Sonar API key or connected account (1 credit per call on prepaid API credits); not part of the free tier. If the store is throttling, the result may be Sonar's stored copy: it then comes back as `{ data, meta }` with `meta.stale: true`, its date in `meta.stale_as_of`, and a `meta.note` to pass on to the user.

App Store Connect sales for one of your own iOS apps: daily first-time downloads, redownloads, in-app purchase units and approximate USD proceeds (`proceeds_usd_approx`, converted with a static FX table — present it as approximate), window totals, and a per-country breakdown sorted by downloads. Same numbers as the Performance page. iOS only. Requires the Agency plan (403 on other plans) AND an App Store Connect connection at /settings/connections. Always check `status`: anything other than `ready` (not_connected, not_ios, app_not_in_account, pending, key_lacks_analytics) means there's no data and `message` says how to fix it — never read an empty series as zero. Days Apple hasn't reported yet have `reported: false` and null metrics.

Find apps in the App Store or Google Play by keyword, e.g. to get an app's store ID before calling other tools. Returns `{ source, data }`: `data` is the matching apps, compact by default (store ID, name, subtitle, developer, category, icon, rating, rating count, price, store URL, list position `rank`); pass fields: "full" for whole listings, or call sonar_app_lookup for one app's full details. `source` says which ordering served the list. `app_store`: Apple's own App Store search order in that storefront (what people see searching on iPhone, editorial cards left out, at most the top 50, cached up to 30 minutes) — fine to report as the app's current position for that search, as a one-off snapshot. `itunes_search`: the iTunes Search API's text-match order, used when Apple's own search couldn't be read — NOT a rank (below the top 10 it can be dozens of places off), so never report a position from it as a rank. `google_play`: Google Play's own search order. For rank history, daily tracking or positions beyond 50, track the keyword (sonar_track_keywords) and read sonar_app_rankings or sonar_keyword_rankings. Works without an API key (free tier, limited daily use per IP). If the store is throttling, the result may be Sonar's stored copy: it then comes back as `{ data, meta }` with `meta.stale: true`, its date in `meta.stale_as_of`, and a `meta.note` to pass on to the user.

WRITE tool — cancel a scheduled reply (manual or auto mode) before it posts; it goes back to draft. Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

Keywords a tracked competitor currently ranks for (last 7 days of SERP data), with difficulty and popularity per keyword. Pass own_app_id for gap analysis: keywords where the competitor ranks but your app doesn't are marked gap=missing. Cursor-paginated (default 50 per page). Requires an Indie plan (trial counts). `popularity` (5-100) is the value Sonar's dashboard shows: Apple's Search Popularity when Apple has a real reading; when Apple reports a keyword below its threshold (popularity_apple 5, about 20) it is Sonar's estimate (at most 18). `popularity_source` says which (apple | proxy), `popularity_apple` is Apple's own reading (null on Android), `popularity_proxy` is Sonar's estimate beside a floored reading.

The full competitive keyword picture for one of your own apps vs every tracked competitor, in one call: live stats (keyword gaps where competitors rank and you don't, winnable gaps, competitors climbing on your tracked keywords, keywords you lead), the top gap/threat/lead rows with metrics, and the latest AI insight if one was generated (opportunity clusters, threat narratives, strengths, posture). Use it when choosing which keywords to target next. Requires an Indie plan (trial counts).

WRITE tool — creates a product in the caller's Sonar workspace and starts tracking the given app(s). A product is the cross-store unit (one iOS + one Android app, or just one of either). Returns the product id and the Sonar app ids needed by sonar_track_keywords and sonar_track_competitor. Own apps count against the plan cap (Indie 10, Agency 50; competitors are not capped) — at the cap the call fails with a 403 plan_limit error. Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

Create an app-store screenshot set for a product, from your own `screens` layouts or a built-in template. The layout JSON format and template ids are documented by sonar_screenshot_layout_guide. The set is immediately visible/editable for humans in the Screenshot Studio (studio_url in the response). Requires an Indie plan (trial counts) and an authorized Sonar account or a write-scope API key.

WRITE tool — delete an alert subscription in the caller's Sonar workspace. Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — delete a product in the caller's Sonar workspace and untrack every app linked to it, with their tracked keywords, discovered keywords, and competitor links. The product's screenshot sets are deleted too. Shared store data (app metadata, snapshots, rank history) is not deleted. Returns { id, deleted, untracked_apps }. Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

Delete one screen from a screenshot set. A set keeps at least one screen — deleting the last one is rejected. Requires an Indie plan (trial counts) and an authorized Sonar account or a write-scope API key.

Permanently delete a screenshot set and everything in it (screens, translations). Irreversible — confirm with the user before deleting work they may want. Requires an Indie plan (trial counts) and an authorized Sonar account or a write-scope API key.

WRITE tool — stop tracking one keyword/app pair in the caller's Sonar workspace. Identify the pair by its tracked-keyword id (from sonar_app_keywords). Equivalent to sonar_untrack_keywords with a single id; that tool removes several (or all) of an app's keywords in one call. Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

Keywords Sonar's discovery engine surfaced for one of your tracked apps but that aren't tracked yet — ranked finds (the app already ranks, unnoticed), competitor gaps, and AI/autocomplete-sourced ideas — each with popularity, difficulty, AI relevance, and an opportunity score (0-100, best first). This is Sonar's "what should I track next" answer; rows can be tracked with sonar_track_keywords (by keyword text + country). Compact by default (no discovered-row id, store or timestamps; keyword_id stays; fields: "full" adds them). Requires an Indie plan (trial counts). `popularity` (5-100) is the value Sonar's dashboard shows: Apple's Search Popularity when Apple has a real reading; when Apple reports a keyword below its threshold (popularity_apple 5, about 20) it is Sonar's estimate (at most 18). `popularity_source` says which (apple | proxy), `popularity_apple` is Apple's own reading (null on Android), `popularity_proxy` is Sonar's estimate beside a floored reading.

WRITE tool — mark a review as not needing a reply (also cancels a scheduled post). Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — write a fresh AI reply draft for a review using the app's instructions (and an optional hint), with English translations. Counts against the monthly AI-draft allowance, then 1 credit per draft. Never posts. Tip: agents can skip this and write the reply themselves with sonar_update_review_reply (not metered). Requires an Indie plan (trial counts) and an authorized Sonar account or an API key with the write scope.

WRITE tool — generates a fresh AI review analysis for a tracked app from its recent reviews (praise/complaint themes, sentiment, feature requests, trend vs the previous run). At most one analysis per app+country every 90 days (429 with the next available time while in cooldown — use sonar_review_insights to read the current one); needs at least 5 recent reviews. Requires a paid (non-trial) Indie plan and an authorized Sonar account or an API key with the write scope.

Get details for one tracked app in the caller's Sonar workspace: store metadata plus daily snapshots of rating, review count, version, and installs. Compact by default (listing basics + the 7 newest snapshots); pass fields: "full" for the description, screenshots, release notes and up to 90 snapshots. Requires an Indie plan (trial counts).

Fetch a screenshot set in full: every screen's layout JSON plus per-screen translation overrides keyed by locale. By default inline image data is replaced with placeholders to keep the response readable. Requires an Indie plan (trial counts).

Difficulty + popularity for a specific keyword (or up to 25 in bulk). Use this when you already know which keywords you care about — costs 1 credit per keyword. Works without an API key for up to 5 keywords/day (free tier, per IP); an API key removes that cap. Use sonar_keyword_search instead when you want related keyword ideas alongside metrics. Answers within about 30 seconds: a keyword that can't be computed in that time comes back as `pending` (queued on Sonar's scrape fleet, not charged, results are being cached) — call again after `retry_after_seconds` for just those keywords. Each row carries `measured_at` (when difficulty was measured) and `popularity_measured_at` (when the popularity value was measured — can be older), both ISO 8601 UTC. `stale: false` means both are under 7 days old; `stale: true` rows are real but older data (refreshed in the background) — check the timestamps when freshness matters. `popularity` (5-100) is the value Sonar's dashboard shows: Apple's Search Popularity when Apple has a real reading; when Apple reports a keyword below its threshold (popularity_apple 5, about 20) it is Sonar's estimate (at most 18). `popularity_source` says which (apple | proxy), `popularity_apple` is Apple's own reading (null on Android), `popularity_proxy` is Sonar's estimate beside a floored reading.

SERP history for one tracked keyword — which apps ranked in the top results on each measured day, newest first (compact by default: no icon URLs; fields: "full" adds them). Use this to see who competes on a keyword and how the top spots shifted over time. The keyword must be tracked in the caller's Sonar workspace. Requires an Indie plan (trial counts).