Get Keywords
get_keywordsRead-only
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, `YYYY-MM-DD`, inclusive. Send it alone and the window is the three years before it. | |
| from | No | Start date, `YYYY-MM-DD`, inclusive. Overrides `period` when both are sent. Send it alone and the window runs to today. | |
| sort | No | `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 | No | Max terms returned, after sorting. Default 100, capped at 300. The answer always says how many the corpus holds. | |
| scope | No | `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 | No | 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 | No | 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 | No | Only keywords carrying this tag. Tag ids come back on the keywords in this tool's own output. Omit for the whole corpus. | |
| country | No | 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 | No | 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 | No | 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 | No | 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 | No | 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | Yes | The order the list came back in. | |
| count | Yes | Terms returned. | |
| scope | Yes | Which scope answered: `app` or `portfolio`. | |
| total | Yes | Terms the corpus holds in this storefront. Larger than `count` when the list was capped. | |
| movers | Yes | The shape of the window in four numbers, **counted over every term in the corpus, not over the rows returned**. This is the only honest basis for a sentence about the corpus, and it is the one to lead with: 8 fell of 103 is a different week from 80 of 103, and a list of 15 rows cannot tell you which you are in. | |
| shared | Yes | Terms two of the account's own apps are both on, worst first, when `include: ["shared"]` was asked for at portfolio scope. Empty otherwise. Read `competing` before calling anything a conflict. | |
| window | Yes | The window actually read, which is not always the one asked for: an inverted range is swapped, a range past three years is shortened, and first-party figures are pulled back to the last day App Store Connect reported. Quote these dates, not the requested ones. | |
| app_ids | Yes | The apps these ranks were read for. | |
| caveats | Yes | Sentences the reader has to hear before the list means what it looks like it means — a capped list and what it was selected for, terms nobody crawled, ranks that are weeks old, a history returned for only some rows, an include that did not apply. They carry the corpus-wide numbers in them so they survive being quoted alone. Pass these on; do not summarise them away. | |
| country | Yes | Storefront the ranks were measured in. | |
| coverage | Yes | How much of this corpus was actually looked at in this window — the answer to "is this a drop or a gap in your crawling", which is otherwise unanswerable from ranks alone and has been guessed at wrongly. AppTail does not crawl every term every day, so sparse coverage on a few terms is normal; a corpus-wide `unmeasured` is not. | |
| keywords | Yes | The terms, in the order `sort` asked for. **A selection, not a sample**: this is the top of a sorted list, so when `truncated` is true these rows are whatever the sort favoured — with the default sort, the worst movers and nothing else. Read them for which terms to ask about next; read `movers` and `coverage` for anything about the corpus. Empty when none are tracked in this storefront — track some with add_keywords. | |
| truncated | Yes | True when `count` is below `total`. Say the list is partial rather than reporting it as the whole corpus. | |
| visibility | No | When `include: ["visibility"]` was asked for: Search Visibility (`score`, `storefronts`) and the daily band counts. **The band counts are not over this corpus**: they count every term the app appeared for that day in this storefront, tracked or not, so they move with whatever anybody crawled and can disagree with the rows (a corpus whose rows show 27 terms in the top 10 can read `top10: 20`). Read them as reach across the store, never as the corpus's state. Each is the last day with a row — a state, not a sum — and null when nothing has been rolled up. The whole block is null when visibility was not asked for. | |
| compared_app_ids | Yes | The competitor ids actually measured. Shorter than what was sent when the cap or an unknown id dropped one. | |
| compare_truncated | Yes | True when competitor ids were dropped for exceeding the cap of 5. |