App Store keyword rankings, competitors, markets, reviews and analytics for iOS apps, from your AI.
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Add an app to the account as one of the user's own. Takes an Apptail app_id, an App Store URL, or a name — resolved and imported the way search_apps does. Tracking starts immediately (rankings, reviews, competitors); measured downloads and proceeds still require connecting App Store Connect in the console, which cannot be done from here.
The app to claim: an Apptail app_id, a full App Store URL, or the app's name. A URL is the reliable form — a name resolves against the whole store, and two apps can share one.
Primary storefront for this app, ISO 3166-1 alpha-2 (e.g. US, DE). Defaults to US. This is the storefront its keywords and rankings are tracked in first; more can be added in the console.
Resolve the app and report what would happen without claiming it. Worth doing when the user gave a name rather than a URL, so they can confirm it is the right app before it counts against their plan.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Add an app to the account as one of the user's own. Takes an Apptail app_id, an App Store URL, or a name — resolved and imported the way search_apps does. Tracking starts immediately (rankings, reviews, competitors); measured downloads and proceeds still require connecting App Store Connect in the console, which cannot be done from here.
| Argument | Type | Description |
|---|---|---|
| app* | string | The app to claim: an Apptail app_id, a full App Store URL, or the app's name. A URL is the reliable form — a name resolves against the whole store, and two apps can share one. |
| country | string | Primary storefront for this app, ISO 3166-1 alpha-2 (e.g. US, DE). Defaults to US. This is the storefront its keywords and rankings are tracked in first; more can be added in the console. |
| dry_run | boolean | Resolve the app and report what would happen without claiming it. Worth doing when the user gave a name rather than a URL, so they can confirm it is the right app before it counts against their plan. |
{
"type": "object",
"required": [
"app"
],
"properties": {
"app": {
"type": "string",
"description": "The app to claim: an Apptail app_id, a full App Store URL, or the app's name. A URL is the reliable form — a name resolves against the whole store, and two apps can share one."
},
"country": {
"type": "string",
"description": "Primary storefront for this app, ISO 3166-1 alpha-2 (e.g. US, DE). Defaults to US. This is the storefront its keywords and rankings are tracked in first; more can be added in the console."
},
"dry_run": {
"type": "boolean",
"description": "Resolve the app and report what would happen without claiming it. Worth doing when the user gave a name rather than a URL, so they can confirm it is the right app before it counts against their plan."
}
}
}Track one or more rival apps against one of YOUR apps. Each competitor can be given as an Apptail app_id, an App Store URL, or just a name — names and URLs are resolved and imported the way search_apps does, so you do NOT need to look up an app_id first. Returns one outcome per item: what was added, what was already tracked, and what a plan limit refused.
| Argument | Type | Description |
|---|---|---|
| app_id* | integer | Apptail app id for one of YOUR apps — from get_account. The rivals are tracked FOR this app: competitor sets belong to an app, not to the account, so removing one later affects only this app. |
| country | string | Storefront to resolve names in, ISO 3166-1 alpha-2 (e.g. US, DE). Omit and it is guessed from the script the name is written in. Ignored for items given as an app_id. |
| dry_run | boolean | Resolve every item and report what would happen, without tracking anything. Use it when the user named apps ambiguously and you want to confirm you found the right ones before changing their account. |
| competitors* | array | The rivals, up to 20. Each item is an Apptail app_id, a full App Store URL, or an app name in any language. Send all of them in one call — the plan limit is checked per item, so a batch that runs out of room still adds what fits and says which items did not. |
{
"type": "object",
"required": [
"app_id",
"competitors"
],
"properties": {
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — from get_account. The rivals are tracked FOR this app: competitor sets belong to an app, not to the account, so removing one later affects only this app."
},
"country": {
"type": "string",
"description": "Storefront to resolve names in, ISO 3166-1 alpha-2 (e.g. US, DE). Omit and it is guessed from the script the name is written in. Ignored for items given as an app_id."
},
"dry_run": {
"type": "boolean",
"description": "Resolve every item and report what would happen, without tracking anything. Use it when the user named apps ambiguously and you want to confirm you found the right ones before changing their account."
},
"competitors": {
"type": "array",
"items": {
"type": "string"
},
"description": "The rivals, up to 20. Each item is an Apptail app_id, a full App Store URL, or an app name in any language. Send all of them in one call — the plan limit is checked per item, so a batch that runs out of room still adds what fits and says which items did not."
}
}
}Start tracking search terms for one of your apps, in one storefront. Send terms, or `keyword_ids` for suggestions returned by discover_keywords — a suggestion MUST be added by id, because re-resolving its term can land on a different keyword row. Counts against the plan's per-app keyword limit; `dry_run` reports what would happen without writing anything. Terms already in the corpus come back under `already_tracked` rather than as an error — that is the state the caller asked for.
| Argument | Type | Description |
|---|---|---|
| app_id* | integer | Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). Keywords are tracked per app. |
| country* | string | Storefront to track these terms in, ISO 3166-1 alpha-2 (e.g. US, GB, DE). Required and not defaulted: a term tracked in the wrong storefront is a wasted keyword slot. Ranks are per storefront — the same term ranks differently in each. |
| dry_run | boolean | Report what would be added, and how many slots are left, without tracking anything. Nothing is written and nothing counts against the plan. |
| keywords | array | Search terms to start tracking, as a user would type them into the App Store (e.g. ["fitness tracker", "workout app"]). Send the whole batch in one call rather than one term per call. Terms we have never seen are created. Every added term whose results are more than a day old is crawled straight away, and positions usually land within a few minutes: a get_keywords read made immediately after this call shows those terms as unmeasured, which means not crawled yet and not that the app is missing from the results. Either this or `keyword_ids` is required. |
Terms an app could be tracking but is not, merged from every source and each labelled with where it came from: what tracked competitors rank for, what the store's similar apps rank for, what those competitors put in their own titles and subtitles, what the store's own mining surfaced, and — reading the listing cold — what the app's own title, subtitle and description suggest. The last is the only source that works on an app added minutes ago; `listing` is the only one that can surface a phrase nobody has ranked for yet, and it offers a phrase only when two or more rivals publish it and Apple reports somebody searching it. Pass `contains` to also match terms already in AppTail's database. Already-tracked and already-dismissed terms are never returned. This is a list of candidates, not a measure of coverage: for how much of a niche's vocabulary the account is missing, and which holes matter most, call get_landscape and read `term_gap`. Discovery can persist shared suggested keyword records, cache generated suggestions, and queue background popularity collection. It does not add those terms to account tracking.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max suggestions, most-searched first. Default 60, capped at 200. The answer always says how many there were. |
| app_id* | integer | Apptail app id to suggest for. get_account for the user's own apps. Suggestions are derived from this app's listing, its rivals and its neighbours, so they are only meaningful for the app they were asked about. |
| source | array | Which sources to read. Omit for all five that need no argument — `competitors`, `similar`, `listing`, `store`, `ai`. `corpus` is a text match against terms AppTail already holds and does nothing without `contains`, which is why "all" does not silently include it. An unknown name is refused rather than ignored. |
Add terms to one storefront's corpus, or take terms out of it. Add for a term the corpus SHOULD hold and does not — a rival's brand, a phrase Apple has never measured the popularity of, the term a thin storefront is really about; a pinned term is kept through every rebuild and refreshed on the same 72-hour cadence as the rest. Remove for a term that does not belong: ANY term can go, and one the heuristic found is also kept out of future rebuilds rather than returning within 72 hours. This is NOT `save_market`: seeds are what the corpus is expanded FROM and changing one re-runs the whole heuristic over that storefront, where these two writes act on single terms in the result.
| Argument | Type | Description |
|---|---|---|
| add | array | Terms to pin, as somebody would type them into the App Store. Send the batch in one call. Terms already in the corpus come back under `already_present` rather than as an error. |
| remove | array | Keyword ids to take out of the corpus — the `keyword_id` on ANY get_market corpus row. A term the heuristic found is also recorded as excluded so rebuilds do not re-derive it; `add` on the same term later clears that again. |
| country* | string | Which storefront's corpus, ISO 3166-1 alpha-2 (e.g. US, DE). Required and not defaulted: a corpus belongs to one storefront, and there is no market-wide term list to add to. |
| market_id* | integer | Apptail market id — from list_markets or save_market. |
Return an account or owned-app summary for a requested period: available measured App Store Connect performance, storefront changes, tracked keyword movements, recorded signals, review volume and the last sent digest. Returns comparison data, coverage and caveats identifying unavailable sections. Reads account data without changing tracking or publishing content.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| app_id | integer | Narrow to one of the account's own apps — get_account lists them. Omit for the whole portfolio, which excludes apps the owner has hidden. |
| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `last_month`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
| compare | string | What to read the period against. `previous` (the default) is the period immediately before — for a calendar month, the calendar month before. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year. |
The account: its apps with Apptail ids, its plan and the limits that can refuse a write, App Store Connect health per app, how fresh the first-party data is, and the storefronts it focuses on. Call this first whenever the request is about "my app" or "my keywords" — every other tool needs an app_id, and the focus countries and hidden apps here are what keep your answer agreeing with what the customer sees in the console.
| Argument | Type | Description |
|---|---|---|
| include_hidden | boolean | Also return apps the owner has set aside. Default true, because they are still tracked and still answerable — each one is marked `hidden: true`, and they must be left out of portfolio totals. Set false for just the working portfolio. |
| include_competitors | boolean | Also return the rival apps tracked under this account's apps, each marked `is_competitor`. Default false: including them makes any portfolio total wrong, and get_competitors is the tool that answers questions about them. |
{
"type": "object",
"properties": {
"include_hidden": {
"type": "boolean",
"description": "Also return apps the owner has set aside. Default true, because they are still tracked and still answerable — each one is marked `hidden: true`, and they must be left out of portfolio totals. Set false for just the working portfolio."
},
"include_competitors": {
"type": "boolean",
"description": "Also return the rival apps tracked under this account's apps, each marked `is_competitor`. Default false: including them makes any portfolio total wrong, and get_competitors is the tool that answers questions about them."
}
}
}Everything AppTail holds about one app, at the depth you ask for. The base answer is the store listing **in one storefront** — the localised title and subtitle a shopper in `country` actually reads, the price and its currency, version, category, release dates, the publisher's ids. `include` adds sections: `prices` (what it costs in every storefront), `ratings` (every storefront's rating and vote count, pooled honestly, plus a daily series and per-storefront movement with `history_days`), `charts` (the charts it currently ranks in), `popularity` (organic reach), `developer` (the publisher and its portfolio), `versions` (release cadence) and `screenshots`. Works for ANY app in the store, not only the user's own. It does NOT return impressions, downloads or revenue — get_performance does, and only for the user's own connected apps.
| Argument | Type | Description |
|---|---|---|
| app_id* | integer | Apptail app id. get_account for the user's own apps, search_apps for any other app in the store. Not the numeric id in an App Store URL (that is apple_app_id). |
| country | string | Storefront to read the listing in (e.g. US, GB, DE). Defaults to the app's primary storefront. Title, subtitle, price, rating and screenshots all differ per storefront, so this changes the answer rather than filtering it — the `name` you get back is the title as published *there*, which for a localised app is not the title in any other market. `ratings.overall`, `ratings.by_country`, `ratings.history` and the `prices` section ignore it — they are every storefront — and `charts` is returned for all of them regardless. |
| include | array | Extra sections to read. Omit for the listing alone, which is the cheap answer. `ratings`, `charts` and `popularity` need a Starter or Pro plan and are refused by name without one — the rest are free. Ask for what the question needs and nothing else: each section is a query. |
List tracked competitor apps for one of your apps, with how many more the plan allows — and `suggested`: up to ten rivals the account does not track yet, ranked by how many of the app's own search terms they sit in the top ten for. Works on an app with no keywords: its listing is read for terms and the store is crawled for them. Read `suggested_basis.terms_pending` before calling a short list complete. Suggestions can persist shared keyword records and queue background crawls. Suggested apps are not added to your competitor watchlist.
| Argument | Type | Description |
|---|---|---|
| app_id* | integer | Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). |
{
"type": "object",
"required": [
"app_id"
],
"properties": {
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id)."
}
}
}The App Store search results for one term in one storefront, on one day: who ranked, in what order, with their names, subtitles and ratings. This is how you find out WHO took the places an app lost — a rank that fell is a fact, and the results page on the day it fell is the reason. Works for ANY term in the store, tracked or not, known to us or not: pass `keyword_id` for a term you already have an id for, or `keyword` + `country` for words a user typed, which resolves the term and crawls the storefront live when what we hold is over a day old. Omit the date for the most recent crawl. A lookup can persist a new shared keyword record and queue a background crawl that updates stored search observations. It does not track the keyword for your account.
| Argument | Type | Description |
|---|---|---|
| date | string | The day to read, `YYYY-MM-DD`. Omit for the most recent crawl, which is the only mode that ever crawls live — naming a day is a question about the past and is answered from what was recorded. A day nobody crawled comes back empty with `crawled: false` rather than as an error; pick one from `crawled_days`, which the answer always returns. |
| limit | integer | How deep to read. Default 25, capped at 50. Below about 25 nobody is competing with you for the term. |
| country | string | Storefront for `keyword`, e.g. "us", "jp". Required with `keyword` and ignored with `keyword_id`, because a keyword already names its storefront. There is no worldwide search results page — every App Store search happens in one country. |
| keyword | string | The search term itself, for words a user typed rather than an id — "sleep tracker", "заметки". Needs `country`. A term nobody has ever looked up is created and the storefront is read live, so this answers for any search in the store and not only for terms Apptail already holds. Prefer `keyword_id` when you have one: it is the exact row, where words go through the store's own normalisation first. |
The account's tracked keywords for an app — or across the whole portfolio — over any window: where each term ranked at the start and end, how far it moved, how many days it held and how many days it was measured, and optionally its day-by-day history, the same terms measured for named competitors, Search Visibility (a 0–100 score per storefront with the terms that moved it), and the terms two of your own apps are both on. Sorted worst movement first by default, so "what dropped" is at the top of a 300-term corpus — which also makes the returned rows a selection rather than a sample: `movers` and `coverage` are counted over the whole corpus and are what a summary comes from. Filter by `contains` to ask about one term by name. This is the tool for every question about tracked terms; it replaces get_tracked_keywords, get_keyword_positions and compare_keyword_positions.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| sort | string | `movement` (the default) puts terms that left the results first, then real drops by size — the top of the list is what to ask about. `rank` is best position first, `volume` is most searched (Apple popularity), `competition` is most crowded. **Every sort selects, so a capped list is never a sample**: a movement-sorted read of 15 terms returns 15 movers whatever the corpus did. Count from `movers` and `coverage`, never from the rows. |
| limit | integer | Max terms returned, after sorting. Default 100, capped at 300. The answer always says how many the corpus holds. |
Who the App Store shows beside one of your apps for the terms it competes on, in one storefront: every app in the niche with how many of your terms it ranks for and owns the top 10 for, its ratings, its review flow and its size, plus which apps arrived or fell out this window — and `term_gap`, how much of the niche's own vocabulary you do not track yet, with the biggest holes ready for add_keywords. This is the niche, not your watchlist: most rows are apps nobody added, and get_competitors answers the other question.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| app_id* | integer | Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). |
| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
| country | string | Storefront to read the niche in (e.g. US, GB). A niche exists per storefront and is never blended across them. Defaults to the first of the account's focus_countries this app is actually tracked in, then the app's primary storefront. |
Read iOS App Store niche data by saved market_id or by query and countries. Returns storefront competition, search visibility, app membership and optional corpus or movement data. Phrase research can create shared keyword records and persist crawled search observations; it does not save an account market. Downloads and revenue are labelled third-party rolling 30-day estimates. Reports per-storefront values, coverage and caveats.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| query | string | A phrase to resolve into a market right now, e.g. "AI calorie tracking". Requires `countries`. Can persist shared keywords and search observations. No market is saved to your account — call save_market with the same phrase to keep it. |
| store | string | Read only this one storefront of a saved market. Omit for every storefront compared, which is where `overlap` and the contest range come from. |
| app_id | integer | Scopes `include: ["app_terms"]` to one app — an Apptail app id from `members`, `search_apps` or `get_landscape`. This is the audit trail for membership: it returns every (term, storefront) place that app holds in this market, how many days it held each, and which clause of the rule put it in `apps` or in `fringe`. Reach for it when the user disagrees with a market's membership, or asks why a particular app is or is not in the niche. |
Read measured App Store Connect impressions, store views, downloads, sales and proceeds for apps connected to the authenticated account. Supports an owned app or portfolio, documented time windows, period comparisons and breakdowns by storefront or traffic source. Returns the actual reporting window, connection coverage and caveats. Does not provide private analytics for apps outside the account.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| grain | string | Bucket size for the series. Omit and it is chosen to fit the window — a day for a month, a week for a year. A grain too fine or too coarse for the window is ignored rather than refused. |
| scope | string | `portfolio` (the default) sums every app the account owns; `app` reports one, and then `app_id` is required. Hidden apps are in the portfolio sum only if the account has not hidden them — they are excluded, matching what the console shows. |
| split | string | Break the totals down. `country` gives one row per storefront Apple named; `source` gives Apple's own attribution — App Store search, browse, app and web referrers. `source` reports the attribution associated with measured downloads. Rows need not add up to the total; the caveats say so. |
Reviews for any app over a window, filtered by storefront, star rating, text, or whether the developer has replied — plus the shape of the period: how many arrived per bucket, what they averaged, and where the app's pooled store rating stood while they did. Reviews exist for every app whether or not App Store Connect is connected, because they are read from the public store. This is the tool for "what are people complaining about": filter it and read the reviews yourself rather than asking for a summary. Every review says whether it can be answered (`can_reply`) and where an existing reply stands (`reply_state`); `reply_to_reviews` is what answers them.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| limit | integer | Max reviews, newest first. Default 25, capped at 200. The answer always says how many matched. |
| app_id* | integer | Apptail app id. get_account for the user's own apps, search_apps for any other. Reviews are readable for any app in the store, including competitors. |
| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. **This tool also takes `all`**, which is the app's whole review history and the only period that reaches a backlog older than three years. Reviews are kept for the life of the app and the console's own reviews screen has no date bound at all, so the ceiling above is about first-party analytics and not about these rows. Send `all` for "what have we never answered" and for anything asking about a review from years ago; the trend then buckets by quarter or year. |
What actually happened, from the record the product keeps: rank moves on tracked terms, chart entries, review spikes, competitor releases and price changes, plus — for the user's own apps only — week-over-week traffic and conversion shifts, download collapses, new reviews and rating moves. Each carries the two numbers behind it and the sentence that states the finding. This is a stored table read, not a reconstruction, so it is both cheaper and more reliable than diffing rank histories yourself. Covers the user's own apps and the competitors tracked under them; a rival's finding never `asks_action`.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| limit | integer | Max findings, newest first. Default 50, capped at 200. The answer always says how many the window actually holds. |
| types | array | Only these kinds of finding. Omit for all of them. An unknown name is refused rather than ignored, so a filtered answer is never returned as though it were unfiltered. |
| app_id | integer | Narrow to one of the user's own apps — get_account lists them. Findings about the competitors tracked under it are included, because a rival taking your places is something that happened to you. Omit for the whole portfolio. |
Get top app charts (free, paid, or grossing) for a store, country, and category.
| Argument | Type | Description |
|---|---|---|
| limit | integer | How deep to read the chart. Default 25, capped at 100. |
| store | string | Only the App Store is covered. Google Play is in the data model but nothing is crawled for it, so omit this. |
| country | string | Storefront to read the chart for (e.g. US, GB, JP). Defaults to US. An unrecognised code falls back to US rather than failing — the reply echoes the storefront actually used, so check it. |
| category | string | Apple category id as a number, e.g. 6014 Games, 6015 Finance, 6017 Education, 6023 Food & Drink, 6013 Health & Fitness, 6012 Lifestyle. Omit for the overall chart across all categories. An id we do not recognise is ignored and you get the overall chart. |
| chart_type | string | Which chart. Default free. Use grossing for revenue questions — top free ranks by downloads and says nothing about money. An unrecognised value falls back to free and the reply says which chart it read. |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "How deep to read the chart. Default 25, capped at 100."
},
"store": {
"enum": [
"apple"
],
"type": "string",
"description": "Only the App Store is covered. Google Play is in the data model but nothing is crawled for it, so omit this."
},
"country": {
"type": "string",
"description": "Storefront to read the chart for (e.g. US, GB, JP). Defaults to US. An unrecognised code falls back to US rather than failing — the reply echoes the storefront actually used, so check it."
},
"category": {
"type": "string",
"description": "Apple category id as a number, e.g. 6014 Games, 6015 Finance, 6017 Education, 6023 Food & Drink, 6013 Health & Fitness, 6012 Lifestyle. Omit for the overall chart across all categories. An id we do not recognise is ignored and you get the overall chart."
},
"chart_type": {
"enum": [
"free",
"paid",
"grossing"
],
"type": "string",
"description": "Which chart. Default free. Use grossing for revenue questions — top free ranks by downloads and says nothing about money. An unrecognised value falls back to free and the reply says which chart it read."
}
}
}List markets saved by the authenticated account, including market ids, storefronts, competition ranges, app counts and observed changes for the requested period. Reads saved account configuration and market observations without creating, updating or deleting markets. Returned ids can be used with get_market.
| Argument | Type | Description |
|---|---|---|
| to | string | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. |
| from | string | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. |
| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
}
}
}Remove one or more competitor tracking relationships for an app owned by the authenticated account. Accepts AppTail app ids, App Store URLs or names. Name and URL resolution can query the public App Store and import shared app records. Removes the selected pairing only; public apps and pairings for other apps remain. Requires write authorisation and returns one outcome per item.
| Argument | Type | Description |
|---|---|---|
| app_id* | integer | Apptail app id for one of YOUR apps — from get_account. Only this app's competitor set is touched. |
| competitors* | array | The rivals to stop tracking, up to 20. Each item is an Apptail app_id (as returned by get_competitors), a store URL, or a name. Ids are the reliable form here — a name is resolved against the whole store, not against what you track. |
{
"type": "object",
"required": [
"app_id",
"competitors"
],
"properties": {
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — from get_account. Only this app's competitor set is touched."
},
"competitors": {
"type": "array",
"items": {
"type": "string"
},
"description": "The rivals to stop tracking, up to 20. Each item is an Apptail app_id (as returned by get_competitors), a store URL, or a name. Ids are the reliable form here — a name is resolved against the whole store, not against what you track."
}
}
}Remove tracked keywords from an app. Frees the slots against the plan limit; position history is kept, so re-adding a term later does not start from nothing.
| Argument | Type | Description |
|---|---|---|
| app_id* | integer | Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). |
| keyword_ids* | array | Apptail keyword ids to stop tracking, as returned by get_keywords. Ids, not terms — two apps can track the same word and only these rows are removed. Frees the slots against your plan limit. Position history is kept, so re-adding a term later does not start from nothing. |
{
"type": "object",
"required": [
"app_id",
"keyword_ids"
],
"properties": {
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id)."
},
"keyword_ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Apptail keyword ids to stop tracking, as returned by get_keywords. Ids, not terms — two apps can track the same word and only these rows are removed. Frees the slots against your plan limit. Position history is kept, so re-adding a term later does not start from nothing."
}
}
}Delete a saved market, or just one of its storefronts. Pass `store` to drop a single storefront and leave the rest of the market with its corpora and its build clocks untouched; omit it to delete the whole market. Deleting frees a slot on the account's plan. The terms themselves are not deleted — they are shared with any other market or tracked app using them.
| Argument | Type | Description |
|---|---|---|
| store | string | Drop only this storefront, ISO 3166-1 alpha-2. Omit to delete the whole market. Dropping the last storefront deletes the market too, because a market asked nowhere is not a market. |
| market_id* | integer | Apptail market id — from list_markets. |
{
"type": "object",
"required": [
"market_id"
],
"properties": {
"store": {
"type": "string",
"description": "Drop only this storefront, ISO 3166-1 alpha-2. Omit to delete the whole market. Dropping the last storefront deletes the market too, because a market asked nowhere is not a market."
},
"market_id": {
"type": "integer",
"description": "Apptail market id — from list_markets."
}
}
}Create, update or remove public App Store review responses for apps owned by the authenticated account, using its connected App Store Connect API key. Requires write authorisation and eligible review ids. Submitted text is sent verbatim under the developer's name. Obtain approval for the exact text or requested removal before submitting. dry_run validates without publication. Accepts up to ten items and returns per-item outcomes; pending means Apple has accepted a response but has not published it.
| Argument | Type | Description |
|---|---|---|
| dry_run | boolean | Check every item and report what would happen, without publishing anything. **Worth using by default here** — it confirms the reviews resolve, the account's key reaches their apps and the text fits, before anything reaches the store. |
| replies* | array | The replies, up to 10 per call. Send them in one call rather than one at a time: each is answered separately, so a batch where one app is not covered still posts the rest and says which it did not. |
{
"type": "object",
"required": [
"replies"
],
"properties": {
"dry_run": {
"type": "boolean",
"description": "Check every item and report what would happen, without publishing anything. **Worth using by default here** — it confirms the reviews resolve, the account's key reaches their apps and the text fits, before anything reaches the store."
},
"replies": {
"type": "array",
"items": {
"type": "object",
"required": [
"review_id"
],
"properties": {
"body": {
"type": "string",
"description": "The reply, exactly as it will appear on the App Store, at most 5970 characters. Write it in the language the review was written in. Required unless `remove` is true. Sending the text that is already on the review does nothing and comes back as `unchanged`, which is not a failure."
},
"remove": {
"type": "boolean",
"description": "Take the existing reply down instead of writing one. `body` is then ignored. Only ever on explicit instruction — a published reply that disappears is visible to everybody who read it."
},
"review_id": {
"type": "integer",
"description": "The Apptail review id, from `get_reviews`. Not the star rating and not the app id."
}
}
},
"description": "The replies, up to 10 per call. Send them in one call rather than one at a time: each is answered separately, so a batch where one app is not covered still posts the rest and says which it did not."
}
}
}Create or update a saved market in the authenticated account from a query, countries and optional per-storefront seed terms. An existing name updates that market, adding storefronts or replacing seed configuration and rebuilding requested storefronts. Persists account configuration and queues background corpus collection using public App Store data. Requires write authorisation. Returns market_id, build status, affected storefronts and caveats; collection may still be pending.
| Argument | Type | Description |
|---|---|---|
| name | string | What to call it. Defaults to `query`. Passing the name of a market this account already has ADDS the new storefronts to it rather than creating a second one. |
| query* | string | The phrase to build the market from, e.g. "AI calorie tracking". Used as the seed in every storefront unless `seeds` overrides it. |
| seeds | object | Per-storefront seed terms, keyed by country code: {"de": ["kalorienzähler"]}. OPTIONAL, and optional per storefront. A storefront you leave out is not seeded from `query`: its terms are read off the localised listings of the leaders of the storefront that WAS phrased, and each one is searched there before it is kept — so it ends up with the local phrasing rather than an English phrase nobody types. Pass a storefront explicitly when you know the local phrase (to use the supplied local terms) or when you want to ask a different question there. Up to five terms each. |
| countries* | array | Storefronts to ask it in, ISO 3166-1 alpha-2 (e.g. ["US","DE"]). Each keeps its own corpus; nothing is blended across them. |
Search for iOS apps by name, bundle ID, or App Store URL. Supports all languages including Cyrillic, Chinese, etc. If the app is not in our database, it will be fetched from the App Store, persisted as a shared public app record, and queued for enrichment. This does not add the app to your account or competitor watchlist. Auto-detects the likely App Store region from the query language (e.g. Cyrillic → Russia, Chinese → China). To add what you find, add_competitors and add_app take the same name or URL directly — you do not have to look up an app_id first.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max results. Default 10, capped at 25. |
| query* | string | App name in any language, a bundle id (com.example.app), or a full App Store URL. Searches Apptail first and falls back to the App Store, importing anything it finds — so this returns a usable app_id even for an app we have never seen. This is how you turn a name a user typed into an app_id. |
| country | string | Storefront to search (e.g. "us", "ru"). Omit and it is guessed from the script the query is written in — Cyrillic implies ru, and so on. Pass it explicitly when the user names a market, because the guess is about language and not about where they sell. |
{
"type": "object",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"description": "Max results. Default 10, capped at 25."
},
"query": {
"type": "string",
"description": "App name in any language, a bundle id (com.example.app), or a full App Store URL. Searches Apptail first and falls back to the App Store, importing anything it finds — so this returns a usable app_id even for an app we have never seen. This is how you turn a name a user typed into an app_id."
},
"country": {
"type": "string",
"description": "Storefront to search (e.g. \"us\", \"ru\"). Omit and it is guessed from the script the query is written in — Cyrillic implies ru, and so on. Pass it explicitly when the user names a market, because the guess is about language and not about where they sell."
}
}
}Put tracked keywords under a tag, in bulk — or clear their tag — and/or say whether they are brand terms for Search Visibility. The tag is named, not looked up: a name that does not exist yet is created. A keyword carries at most one tag, so assigning replaces whatever it had. `brand` is separate from tags: `own` (your app's name) and `competitor` (a rival's name) leave the terms out of the visibility score, `none` counts them whatever detection says, `auto` hands them back to detection. Send `brand` without `tag` to change only that — the tags stay as they are. This is the tool for organising a large corpus after reading it with get_keywords, which is drudgery in the console and one call here.
| Argument | Type | Description |
|---|---|---|
| tag | string | The tag name to put them under. Created if it does not exist. Omit — or send null — to clear the tag off these keywords instead. |
| brand | string | Whether these terms are somebody's name, for Search Visibility (get_keywords `include: ["visibility"]`). `own` = your app's name, `competitor` = a rival's: both are listed and left out of the score, because you rank #1 for your own name whatever your ASO does. `none` = count them anyway. `auto` = let title-word detection decide again. Detection is shown on each row's `brand.reason`; override it when it is wrong (a transliterated rival name, a generic word it took for a name). Omit to leave the brand decision alone. Sent without `tag`, only the brand decision changes. |
| color | string | Hex colour for a tag being created, e.g. "#2563eb". Ignored when the tag already exists. Omit and one is picked from the palette that the app is not already using. |
| app_id* |
| keyword_ids | array | Apptail keyword ids to start tracking — the `keyword_id` on a discover_keywords row. Use this rather than the term whenever you have an id: a term is re-resolved and can land on a different keyword row than the one you were shown. |
{
"type": "object",
"required": [
"app_id",
"country"
],
"properties": {
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). Keywords are tracked per app."
},
"country": {
"type": "string",
"description": "Storefront to track these terms in, ISO 3166-1 alpha-2 (e.g. US, GB, DE). Required and not defaulted: a term tracked in the wrong storefront is a wasted keyword slot. Ranks are per storefront — the same term ranks differently in each."
},
"dry_run": {
"type": "boolean",
"description": "Report what would be added, and how many slots are left, without tracking anything. Nothing is written and nothing counts against the plan."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Search terms to start tracking, as a user would type them into the App Store (e.g. [\"fitness tracker\", \"workout app\"]). Send the whole batch in one call rather than one term per call. Terms we have never seen are created. Every added term whose results are more than a day old is crawled straight away, and positions usually land within a few minutes: a get_keywords read made immediately after this call shows those terms as unmeasured, which means not crawled yet and not that the app is missing from the results. Either this or `keyword_ids` is required."
},
"keyword_ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Apptail keyword ids to start tracking — the `keyword_id` on a discover_keywords row. Use this rather than the term whenever you have an id: a term is re-resolved and can land on a different keyword row than the one you were shown."
}
}
}| country |
| string |
| Storefront to suggest for (e.g. US, DE). Defaults to the app's primary storefront — which is only one of them: an app localized into several languages is searched for in several storefronts, so call once per entry in get_app's `listing_storefronts`. Discovery is per storefront and never a blend: a German term is not a translation of an English one — `spritverbrauch` beats `kraftstoffverbrauch` by a margin no dictionary would tell you. |
| contains | string | Only terms containing this text. With `source: ["corpus"]` this is a search of AppTail's keyword database. Note it searches terms AppTail holds, not the App Store: a phrase nobody has ever tracked returns nothing, and to start tracking a brand-new term you pass it straight to add_keywords. |
{
"type": "object",
"required": [
"app_id"
],
"properties": {
"limit": {
"type": "integer",
"description": "Max suggestions, most-searched first. Default 60, capped at 200. The answer always says how many there were."
},
"app_id": {
"type": "integer",
"description": "Apptail app id to suggest for. get_account for the user's own apps. Suggestions are derived from this app's listing, its rivals and its neighbours, so they are only meaningful for the app they were asked about."
},
"source": {
"type": "array",
"items": {
"enum": [
"competitors",
"similar",
"listing",
"store",
"ai",
"corpus",
"all"
],
"type": "string"
},
"description": "Which sources to read. Omit for all five that need no argument — `competitors`, `similar`, `listing`, `store`, `ai`. `corpus` is a text match against terms AppTail already holds and does nothing without `contains`, which is why \"all\" does not silently include it. An unknown name is refused rather than ignored."
},
"country": {
"type": "string",
"description": "Storefront to suggest for (e.g. US, DE). Defaults to the app's primary storefront — which is only one of them: an app localized into several languages is searched for in several storefronts, so call once per entry in get_app's `listing_storefronts`. Discovery is per storefront and never a blend: a German term is not a translation of an English one — `spritverbrauch` beats `kraftstoffverbrauch` by a margin no dictionary would tell you."
},
"contains": {
"type": "string",
"description": "Only terms containing this text. With `source: [\"corpus\"]` this is a search of AppTail's keyword database. Note it searches terms AppTail holds, not the App Store: a phrase nobody has ever tracked returns nothing, and to start tracking a brand-new term you pass it straight to add_keywords."
}
}
}{
"type": "object",
"required": [
"market_id",
"country"
],
"properties": {
"add": {
"type": "array",
"items": {
"type": "string"
},
"description": "Terms to pin, as somebody would type them into the App Store. Send the batch in one call. Terms already in the corpus come back under `already_present` rather than as an error."
},
"remove": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Keyword ids to take out of the corpus — the `keyword_id` on ANY get_market corpus row. A term the heuristic found is also recorded as excluded so rebuilds do not re-derive it; `add` on the same term later clears that again."
},
"country": {
"type": "string",
"description": "Which storefront's corpus, ISO 3166-1 alpha-2 (e.g. US, DE). Required and not defaulted: a corpus belongs to one storefront, and there is no market-wide term list to add to."
},
"market_id": {
"type": "integer",
"description": "Apptail market id — from list_markets or save_market."
}
}
}| country | string | Storefront for the keyword half only; the money is reported across all of them with a per-storefront split. Defaults to the app's primary storefront. Ranks only exist per storefront. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"app_id": {
"type": "integer",
"description": "Narrow to one of the account's own apps — get_account lists them. Omit for the whole portfolio, which excludes apps the owner has hidden."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `last_month`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
},
"compare": {
"enum": [
"none",
"previous",
"year_ago"
],
"type": "string",
"description": "What to read the period against. `previous` (the default) is the period immediately before — for a calendar month, the calendar month before. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year."
},
"country": {
"type": "string",
"description": "Storefront for the keyword half only; the money is reported across all of them with a per-storefront split. Defaults to the app's primary storefront. Ranks only exist per storefront."
}
}
}| history_days | integer | With `include: ["ratings"]`, also return the rating and the vote count day by day, this many days back from today, **and how each storefront moved over that window** — `ratings_gained` and `rating_change` on every row of `ratings.by_country`. Capped at 365. Ask for it whenever the question is whether a rating is *moving* or *where* it is moving: an average slides for weeks before enough people write about it, and a cross-section cannot tell a market that has always been low from one that fell this month. Ignored without the `ratings` include. |
{
"type": "object",
"required": [
"app_id"
],
"properties": {
"app_id": {
"type": "integer",
"description": "Apptail app id. get_account for the user's own apps, search_apps for any other app in the store. Not the numeric id in an App Store URL (that is apple_app_id)."
},
"country": {
"type": "string",
"description": "Storefront to read the listing in (e.g. US, GB, DE). Defaults to the app's primary storefront. Title, subtitle, price, rating and screenshots all differ per storefront, so this changes the answer rather than filtering it — the `name` you get back is the title as published *there*, which for a localised app is not the title in any other market. `ratings.overall`, `ratings.by_country`, `ratings.history` and the `prices` section ignore it — they are every storefront — and `charts` is returned for all of them regardless."
},
"include": {
"type": "array",
"items": {
"enum": [
"ratings",
"charts",
"popularity",
"developer",
"versions",
"screenshots",
"prices"
],
"type": "string"
},
"description": "Extra sections to read. Omit for the listing alone, which is the cheap answer. `ratings`, `charts` and `popularity` need a Starter or Pro plan and are refused by name without one — the rest are free. Ask for what the question needs and nothing else: each section is a query."
},
"history_days": {
"type": "integer",
"description": "With `include: [\"ratings\"]`, also return the rating and the vote count day by day, this many days back from today, **and how each storefront moved over that window** — `ratings_gained` and `rating_change` on every row of `ratings.by_country`. Capped at 365. Ask for it whenever the question is whether a rating is *moving* or *where* it is moving: an average slides for weeks before enough people write about it, and a cross-section cannot tell a market that has always been low from one that fell this month. Ignored without the `ratings` include."
}
}
}| keyword_id | integer | Apptail keyword id — from get_keywords or discover_keywords, or off a `rank.move` signal. The storefront is fixed by the keyword itself; a term is tracked per country. Give this OR `keyword` + `country`, not both. |
{
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "The day to read, `YYYY-MM-DD`. Omit for the most recent crawl, which is the only mode that ever crawls live — naming a day is a question about the past and is answered from what was recorded. A day nobody crawled comes back empty with `crawled: false` rather than as an error; pick one from `crawled_days`, which the answer always returns."
},
"limit": {
"type": "integer",
"description": "How deep to read. Default 25, capped at 50. Below about 25 nobody is competing with you for the term."
},
"country": {
"type": "string",
"description": "Storefront for `keyword`, e.g. \"us\", \"jp\". Required with `keyword` and ignored with `keyword_id`, because a keyword already names its storefront. There is no worldwide search results page — every App Store search happens in one country."
},
"keyword": {
"type": "string",
"description": "The search term itself, for words a user typed rather than an id — \"sleep tracker\", \"заметки\". Needs `country`. A term nobody has ever looked up is created and the storefront is read live, so this answers for any search in the store and not only for terms Apptail already holds. Prefer `keyword_id` when you have one: it is the exact row, where words go through the store's own normalisation first."
},
"keyword_id": {
"type": "integer",
"description": "Apptail keyword id — from get_keywords or discover_keywords, or off a `rank.move` signal. The storefront is fixed by the keyword itself; a term is tracked per country. Give this OR `keyword` + `country`, not both."
}
}
}| scope | string | `app` (the default) reads one app's corpus and needs `app_id`. `portfolio` reads every app the account owns and reports each term under whichever of them ranks best for it — that is the scope `include: ["shared"]` needs, and hidden apps are excluded from it. |
| app_id | integer | Apptail app id for one of YOUR apps — get_account lists them. Required for `scope: "app"`. Not the numeric id in an App Store URL (that is apple_app_id). |
| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
| tag_id | integer | Only keywords carrying this tag. Tag ids come back on the keywords in this tool's own output. Omit for the whole corpus. |
| country | string | Storefront to read ranks in (e.g. US, GB). Defaults to the app's primary storefront. Ranks only exist per storefront — the same term ranks differently in each — so one call answers for one market. |
| include | array | Extra blocks. `history` adds a day-by-day series per term, capped at 25 terms — pair it with `keyword_ids` for specific terms. `visibility` adds **Search Visibility** — the 0–100 answer to "is our ASO working here", its like-for-like change and the terms that moved it, plus a line per storefront — and each row's `points_change` and `brand`; also the daily top-N counts, which are over every term the app appeared for, not over this corpus. `shared` adds the terms two of your own apps are both on, and needs `scope: "portfolio"`. |
| contains | string | Only terms whose text carries this substring, matched case-insensitively and applied before the sort and the cap. This is how to ask about a term by name — "how is `mpg` doing" — without looking up its id first, and the only way to see a term that sits mid-table by movement and so never reaches the top of a sorted list. |
| keyword_ids | array | Only these terms, by Apptail keyword id — from this tool's own output or discover_keywords. Ids the account does not track are still answered when the scope is one app, because "how is my app doing for this term" is a real question; the answer says so. Omit for the whole corpus. |
| compare_with | array | Apptail app ids to measure on these same terms — from get_competitors or search_apps. Rivals are measured on YOUR corpus, not theirs. At most 5 are used and the answer names which; send the ones that matter first. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"sort": {
"enum": [
"movement",
"rank",
"volume",
"competition"
],
"type": "string",
"description": "`movement` (the default) puts terms that left the results first, then real drops by size — the top of the list is what to ask about. `rank` is best position first, `volume` is most searched (Apple popularity), `competition` is most crowded. **Every sort selects, so a capped list is never a sample**: a movement-sorted read of 15 terms returns 15 movers whatever the corpus did. Count from `movers` and `coverage`, never from the rows."
},
"limit": {
"type": "integer",
"description": "Max terms returned, after sorting. Default 100, capped at 300. The answer always says how many the corpus holds."
},
"scope": {
"enum": [
"app",
"portfolio"
],
"type": "string",
"description": "`app` (the default) reads one app's corpus and needs `app_id`. `portfolio` reads every app the account owns and reports each term under whichever of them ranks best for it — that is the scope `include: [\"shared\"]` needs, and hidden apps are excluded from it."
},
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — get_account lists them. Required for `scope: \"app\"`. Not the numeric id in an App Store URL (that is apple_app_id)."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
},
"tag_id": {
"type": "integer",
"description": "Only keywords carrying this tag. Tag ids come back on the keywords in this tool's own output. Omit for the whole corpus."
},
"country": {
"type": "string",
"description": "Storefront to read ranks in (e.g. US, GB). Defaults to the app's primary storefront. Ranks only exist per storefront — the same term ranks differently in each — so one call answers for one market."
},
"include": {
"type": "array",
"items": {
"enum": [
"history",
"visibility",
"shared"
],
"type": "string"
},
"description": "Extra blocks. `history` adds a day-by-day series per term, capped at 25 terms — pair it with `keyword_ids` for specific terms. `visibility` adds **Search Visibility** — the 0–100 answer to \"is our ASO working here\", its like-for-like change and the terms that moved it, plus a line per storefront — and each row's `points_change` and `brand`; also the daily top-N counts, which are over every term the app appeared for, not over this corpus. `shared` adds the terms two of your own apps are both on, and needs `scope: \"portfolio\"`."
},
"contains": {
"type": "string",
"description": "Only terms whose text carries this substring, matched case-insensitively and applied before the sort and the cap. This is how to ask about a term by name — \"how is `mpg` doing\" — without looking up its id first, and the only way to see a term that sits mid-table by movement and so never reaches the top of a sorted list."
},
"keyword_ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Only these terms, by Apptail keyword id — from this tool's own output or discover_keywords. Ids the account does not track are still answered when the scope is one app, because \"how is my app doing for this term\" is a real question; the answer says so. Omit for the whole corpus."
},
"compare_with": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Apptail app ids to measure on these same terms — from get_competitors or search_apps. Rivals are measured on YOUR corpus, not theirs. At most 5 are used and the answer names which; send the ones that matter first."
}
}
}{
"type": "object",
"required": [
"app_id"
],
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id)."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
},
"country": {
"type": "string",
"description": "Storefront to read the niche in (e.g. US, GB). A niche exists per storefront and is never blended across them. Defaults to the first of the account's focus_countries this app is actually tracked in, then the app's primary storefront."
}
}
}| period |
| string |
| The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
| include | array | Extra sections, each costing a query: `members` (the leaderboard), `corpus` (every term with why it is in), `movement` (who arrived and who left), `app_terms` (which terms ONE app holds here and whether that makes it a competitor — needs `app_id`). Ask for what the question needs. |
| countries | array | Storefronts to ask the question in, ISO 3166-1 alpha-2 (e.g. ["US","GB","DE"]). Required with `query`. Each storefront gets its own corpus seeded from the same phrase; that is deliberate, and a phrase nobody searches in a storefront comes back with a thin corpus, which is itself the finding. |
| market_id | integer | Apptail market id for a market this account has saved — from list_markets. A saved market is a pure read: no crawling, sub-second. Send this OR `query`, not both. |
| budget_seconds | integer | How long a live `query` may spend crawling, shared across ALL storefronts rather than each. Default 5, max 30. It is rarely the binding limit — at most 12 terms are crawled per call whatever the clock says. |
| new_within_days | integer | Keep only apps FIRST RELEASED inside this many days — "what has launched into this niche lately". Applied to every app ranking for the corpus before the list is cut, so these are the new apps in the market and not the new apps among its leaders; a young app is rarely a leader yet, so filtering the leaderboard itself would answer nothing. Affects `members` only. `share` stays a share of the WHOLE market, which is the point of it. Not the same question as `movement`: that is who started ranking here, which is mostly apps that are not new at all. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"query": {
"type": "string",
"description": "A phrase to resolve into a market right now, e.g. \"AI calorie tracking\". Requires `countries`. Can persist shared keywords and search observations. No market is saved to your account — call save_market with the same phrase to keep it."
},
"store": {
"type": "string",
"description": "Read only this one storefront of a saved market. Omit for every storefront compared, which is where `overlap` and the contest range come from."
},
"app_id": {
"type": "integer",
"description": "Scopes `include: [\"app_terms\"]` to one app — an Apptail app id from `members`, `search_apps` or `get_landscape`. This is the audit trail for membership: it returns every (term, storefront) place that app holds in this market, how many days it held each, and which clause of the rule put it in `apps` or in `fringe`. Reach for it when the user disagrees with a market's membership, or asks why a particular app is or is not in the niche."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
},
"include": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra sections, each costing a query: `members` (the leaderboard), `corpus` (every term with why it is in), `movement` (who arrived and who left), `app_terms` (which terms ONE app holds here and whether that makes it a competitor — needs `app_id`). Ask for what the question needs."
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Storefronts to ask the question in, ISO 3166-1 alpha-2 (e.g. [\"US\",\"GB\",\"DE\"]). Required with `query`. Each storefront gets its own corpus seeded from the same phrase; that is deliberate, and a phrase nobody searches in a storefront comes back with a thin corpus, which is itself the finding."
},
"market_id": {
"type": "integer",
"description": "Apptail market id for a market this account has saved — from list_markets. A saved market is a pure read: no crawling, sub-second. Send this OR `query`, not both."
},
"budget_seconds": {
"type": "integer",
"description": "How long a live `query` may spend crawling, shared across ALL storefronts rather than each. Default 5, max 30. It is rarely the binding limit — at most 12 terms are crawled per call whatever the clock says."
},
"new_within_days": {
"type": "integer",
"description": "Keep only apps FIRST RELEASED inside this many days — \"what has launched into this niche lately\". Applied to every app ranking for the corpus before the list is cut, so these are the new apps in the market and not the new apps among its leaders; a young app is rarely a leader yet, so filtering the leaderboard itself would answer nothing. Affects `members` only. `share` stays a share of the WHOLE market, which is the point of it. Not the same question as `movement`: that is who started ranking here, which is mostly apps that are not new at all."
}
}
}| app_id | integer | Apptail app id, required when `scope` is `app`. Must be one of the user's own apps — get_account lists them. Measured analytics require an authorised App Store Connect connection for the account. |
| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
| compare | string | What to read the window against. `previous` (the default) is the period immediately before — for a calendar month that is the calendar month before, not the same number of days. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year. |
| include_apps | boolean | On `portfolio` scope, also return one row per app so a portfolio move can be attributed to the app that caused it. Default false. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"grain": {
"enum": [
"day",
"week",
"month",
"quarter",
"year"
],
"type": "string",
"description": "Bucket size for the series. Omit and it is chosen to fit the window — a day for a month, a week for a year. A grain too fine or too coarse for the window is ignored rather than refused."
},
"scope": {
"enum": [
"portfolio",
"app"
],
"type": "string",
"description": "`portfolio` (the default) sums every app the account owns; `app` reports one, and then `app_id` is required. Hidden apps are in the portfolio sum only if the account has not hidden them — they are excluded, matching what the console shows."
},
"split": {
"enum": [
"none",
"country",
"source"
],
"type": "string",
"description": "Break the totals down. `country` gives one row per storefront Apple named; `source` gives Apple's own attribution — App Store search, browse, app and web referrers. `source` reports the attribution associated with measured downloads. Rows need not add up to the total; the caveats say so."
},
"app_id": {
"type": "integer",
"description": "Apptail app id, required when `scope` is `app`. Must be one of the user's own apps — get_account lists them. Measured analytics require an authorised App Store Connect connection for the account."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
},
"compare": {
"enum": [
"none",
"previous",
"year_ago"
],
"type": "string",
"description": "What to read the window against. `previous` (the default) is the period immediately before — for a calendar month that is the calendar month before, not the same number of days. `year_ago` is the same dates a year earlier, for comparison with the corresponding period in the previous year."
},
"include_apps": {
"type": "boolean",
"description": "On `portfolio` scope, also return one row per app so a portfolio move can be attributed to the app that caused it. Default false."
}
}
}| rating | array | Only these star ratings, e.g. `[1, 2]` for the critical ones. Omit for all five. The `summary` counts are deliberately NOT filtered by this, so a call asking only for one-stars still learns how many reviews the period actually held. |
| country | string | Only reviews from this storefront (e.g. de). Omit for every storefront, which is usually right — one storefront's reviews are a thin sample. Send it when `ratings.by_country` on get_app has pointed at a market, which is the follow-up that finds out why it is low. |
| contains | string | Only reviews whose title or body contains this text, case-insensitively. Title as well as body, because a complaint is as often the headline as the paragraph. This is how you check a hypothesis — "crash", "subscription", "ads" — rather than reading everything. |
| unanswered | boolean | Only reviews the developer has never replied to. False or omitted for all of them. Combined with `rating: [1, 2]` this is the work queue the console leads with — and **a backlog has no window**, so send `period: "all"` when you mean all of it. `summary.unanswered` is the whole-history count either way, and a list that is smaller than it is a windowed list, not a shorter backlog. |
{
"type": "object",
"required": [
"app_id"
],
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"limit": {
"type": "integer",
"description": "Max reviews, newest first. Default 25, capped at 200. The answer always says how many matched."
},
"app_id": {
"type": "integer",
"description": "Apptail app id. get_account for the user's own apps, search_apps for any other. Reviews are readable for any app in the store, including competitors."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. **This tool also takes `all`**, which is the app's whole review history and the only period that reaches a backlog older than three years. Reviews are kept for the life of the app and the console's own reviews screen has no date bound at all, so the ceiling above is about first-party analytics and not about these rows. Send `all` for \"what have we never answered\" and for anything asking about a review from years ago; the trend then buckets by quarter or year."
},
"rating": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Only these star ratings, e.g. `[1, 2]` for the critical ones. Omit for all five. The `summary` counts are deliberately NOT filtered by this, so a call asking only for one-stars still learns how many reviews the period actually held."
},
"country": {
"type": "string",
"description": "Only reviews from this storefront (e.g. de). Omit for every storefront, which is usually right — one storefront's reviews are a thin sample. Send it when `ratings.by_country` on get_app has pointed at a market, which is the follow-up that finds out why it is low."
},
"contains": {
"type": "string",
"description": "Only reviews whose title or body contains this text, case-insensitively. Title as well as body, because a complaint is as often the headline as the paragraph. This is how you check a hypothesis — \"crash\", \"subscription\", \"ads\" — rather than reading everything."
},
"unanswered": {
"type": "boolean",
"description": "Only reviews the developer has never replied to. False or omitted for all of them. Combined with `rating: [1, 2]` this is the work queue the console leads with — and **a backlog has no window**, so send `period: \"all\"` when you mean all of it. `summary.unanswered` is the whole-history count either way, and a list that is smaller than it is a windowed list, not a shorter backlog."
}
}
}| period | string | The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling. |
| include_sent | boolean | Mark the findings that already went out in an alert digest the user has read. Default false. Set it whenever you are about to summarise a period for someone: without it you cannot tell news from something they read at breakfast, and repeating the second as the first is how an assistant stops being believed. |
| min_severity | string | Floor on how loudly a finding speaks. Default `neutral`, which is everything. `warning` drops a rival shipping a point release, which is worth knowing and not worth acting on. It is NOT the same as "what needs my attention" — read `asks_action` on each finding for that: a competitor taking a run of 1–2★ reviews is a warning about somebody else's week and asks nothing of this user. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it."
},
"from": {
"type": "string",
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today."
},
"limit": {
"type": "integer",
"description": "Max findings, newest first. Default 50, capped at 200. The answer always says how many the window actually holds."
},
"types": {
"type": "array",
"items": {
"enum": [
"rank.move",
"chart.enter",
"review.spike",
"competitor.release",
"price.change",
"traffic.shift",
"conversion.shift",
"downloads.drop",
"review.new",
"rating.change"
],
"type": "string"
},
"description": "Only these kinds of finding. Omit for all of them. An unknown name is refused rather than ignored, so a filtered answer is never returned as though it were unfiltered."
},
"app_id": {
"type": "integer",
"description": "Narrow to one of the user's own apps — get_account lists them. Findings about the competitors tracked under it are included, because a rival taking your places is something that happened to you. Omit for the whole portfolio."
},
"period": {
"type": "string",
"description": "The window to report on. A calendar month as `2026-07`, a calendar year as `2026`, `last_month`, `this_month`, `last_year`, or a trailing window: `today`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `730d`, `1095d`. Defaults to `30d`. A calendar period is compared against the calendar period before it — July against June, not against the 31 days ending 30 June. Three years is the ceiling."
},
"include_sent": {
"type": "boolean",
"description": "Mark the findings that already went out in an alert digest the user has read. Default false. Set it whenever you are about to summarise a period for someone: without it you cannot tell news from something they read at breakfast, and repeating the second as the first is how an assistant stops being believed."
},
"min_severity": {
"enum": [
"neutral",
"opportunity",
"warning",
"critical"
],
"type": "string",
"description": "Floor on how loudly a finding speaks. Default `neutral`, which is everything. `warning` drops a rival shipping a point release, which is worth knowing and not worth acting on. It is NOT the same as \"what needs my attention\" — read `asks_action` on each finding for that: a competitor taking a run of 1–2★ reviews is a warning about somebody else's week and asks nothing of this user."
}
}
}{
"type": "object",
"required": [
"query",
"countries"
],
"properties": {
"name": {
"type": "string",
"description": "What to call it. Defaults to `query`. Passing the name of a market this account already has ADDS the new storefronts to it rather than creating a second one."
},
"query": {
"type": "string",
"description": "The phrase to build the market from, e.g. \"AI calorie tracking\". Used as the seed in every storefront unless `seeds` overrides it."
},
"seeds": {
"type": "object",
"description": "Per-storefront seed terms, keyed by country code: {\"de\": [\"kalorienzähler\"]}. OPTIONAL, and optional per storefront. A storefront you leave out is not seeded from `query`: its terms are read off the localised listings of the leaders of the storefront that WAS phrased, and each one is searched there before it is kept — so it ends up with the local phrasing rather than an English phrase nobody types. Pass a storefront explicitly when you know the local phrase (to use the supplied local terms) or when you want to ask a different question there. Up to five terms each."
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Storefronts to ask it in, ISO 3166-1 alpha-2 (e.g. [\"US\",\"DE\"]). Each keeps its own corpus; nothing is blended across them."
}
}
}| integer |
| Apptail app id for one of YOUR apps — from get_account. Tags belong to an app. |
| keyword_ids* | array | Apptail keyword ids to tag, as returned by get_keywords. Ids, not terms. Up to 500 in one call. A keyword the app does not track is reported back rather than silently ignored. |
{
"type": "object",
"required": [
"app_id",
"keyword_ids"
],
"properties": {
"tag": {
"type": "string",
"description": "The tag name to put them under. Created if it does not exist. Omit — or send null — to clear the tag off these keywords instead."
},
"brand": {
"enum": [
"own",
"competitor",
"none",
"auto"
],
"type": "string",
"description": "Whether these terms are somebody's name, for Search Visibility (get_keywords `include: [\"visibility\"]`). `own` = your app's name, `competitor` = a rival's: both are listed and left out of the score, because you rank #1 for your own name whatever your ASO does. `none` = count them anyway. `auto` = let title-word detection decide again. Detection is shown on each row's `brand.reason`; override it when it is wrong (a transliterated rival name, a generic word it took for a name). Omit to leave the brand decision alone. Sent without `tag`, only the brand decision changes."
},
"color": {
"type": "string",
"description": "Hex colour for a tag being created, e.g. \"#2563eb\". Ignored when the tag already exists. Omit and one is picked from the palette that the app is not already using."
},
"app_id": {
"type": "integer",
"description": "Apptail app id for one of YOUR apps — from get_account. Tags belong to an app."
},
"keyword_ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Apptail keyword ids to tag, as returned by get_keywords. Ids, not terms. Up to 500 in one call. A keyword the app does not track is reported back rather than silently ignored."
}
}
}