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.
View input schema
{
"type": "object",
"properties": {
"scope": {
"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.",
"enum": [
"app",
"portfolio"
],
"type": "string"
},
"app_id": {
"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).",
"type": "integer"
},
"country": {
"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.",
"type": "string"
},
"period": {
"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.",
"type": "string"
},
"from": {
"description": "Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today.",
"type": "string"
},
"to": {
"description": "End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it.",
"type": "string"
},
"keyword_ids": {
"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.",
"items": {
"type": "integer"
},
"type": "array"
},
"compare_with": {
"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.",
"items": {
"type": "integer"
},
"type": "array"
},
"contains": {
"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.",
"type": "string"
},
"sort": {
"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.",
"enum": [
"movement",
"rank",
"volume",
"competition"
],
"type": "string"
},
"include": {
"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\"`.",
"items": {
"enum": [
"history",
"visibility",
"shared"
],
"type": "string"
},
"type": "array"
},
"tag_id": {
"description": "Only keywords carrying this tag. Tag ids come back on the keywords in this tool's own output. Omit for the whole corpus.",
"type": "integer"
},
"limit": {
"description": "Max terms returned, after sorting. Default 100, capped at 300. The answer always says how many the corpus holds.",
"type": "integer"
}
}
}