Query bank

The query bank holds the keywords built from a product’s prompts. These read-only commands show the keyword list, how one targeted keyword’s page is doing, and whether targeting paid off. Pass --scope <org-slug>/<product-slug> to select the product.

tpc query-bank keywords --scope pro-org/my-product
tpc query-bank keyword <keywordId> --scope pro-org/my-product
tpc query-bank results --scope pro-org/my-product

With --format json, each command prints the response of its /api/v1 route with the field names unchanged. results wraps it as { "comparison": ... }.

List keywords

tpc query-bank keywords --scope pro-org/my-product --page 1 --page-size 25

Lists the keywords with their prompt and search counts and the page each one targets, if any.

Flag	Description
`--page`	One-based page number. Default: 1.
`--page-size`	Keywords per page, 1 to 100. Default: 10.

Example output:

PRODUCT:	my-product
PAGE:	1 of 1

ID      KEYWORD                       PROMPTS  SEARCHES  TARGET PAGE                                  TARGETED SINCE
kw_123  best expense tracking app     4        9         https://example.com/guides/expense-tracking  2026-11-02
kw_124  expense report software       3        6         (no page yet)                                2026-11-02
kw_125  track receipts automatically  2        3         -                                            -

Total: 3

JSON fields: data (each row has id, label, promptCount, searchCount, and target, which is { targetedAt, pageUrl } or null), rankCheck, totalPages, totalItems, and stats.

Show a keyword

tpc query-bank keyword <keywordId> --scope pro-org/my-product
tpc query-bank keyword <keywordId> --from 2026-06-01 --to 2026-06-30 --scope pro-org/my-product

Shows one keyword with its prompts, rank history (grouped by engine, newest first within each, up to 20 per engine), recommendation, and, when it is targeted, the page status.

Flag	Description
`--from`, `--to`	Date window for the page status and search performance, `YYYY-MM-DD`. Both required together. Defaults to the keyword’s own target date through today, at most 180 days back.

Example output:

PRODUCT:	my-product
KEYWORD:	best expense tracking app
PROMPTS:	4
TARGET:	https://example.com/guides/expense-tracking (since 2026-11-02)
STATUS:	ranking
RECOMMENDATION:	improve https://example.com/guides/expense-tracking (rank 4)

GOOGLE SEARCH PERFORMANCE:	2026-11-02 to 2026-11-13, as of 2026-11-10
IMPRESSIONS:	120
CLICKS:	9
AVERAGE POSITION:	6.4
SEARCH                     IMPRESSIONS  CLICKS  POSITION  THIS KEYWORD
best expense tracking app  80           7       5.2       yes
expense report software    40           2       8.9
1 of this keyword's searches showed this page.

ENGINE  INDEXED  SOURCE  RANK
google  -        -       4
bing    -        -       -
brave   -        -       -

INDEXED shows true or false when a lookup confirmed it, Couldn't confirm when the lookup returned a full page of results, or the engine reported more than it returned, and none was this exact page, and - when there is no lookup result yet or the engine has no page lookup. SOURCE shows search_console when Google’s URL Inspection in your connected Search Console property answered, search when a search for the page answered, and - when it hasn’t been checked. When Search Console answered for Google, the text output adds google reason: (when the page is not indexed), google last crawled: (when Google has crawled the page) and google canonical: (when Google treats a different address as the main version) lines. When Search Console needs reconnecting, it adds a SEARCH CONSOLE: line saying Google checks use a search until you reconnect. When citations are incomplete, the text output adds a CITATIONS: line. For a targeted keyword, the text output has a GOOGLE SEARCH PERFORMANCE: section from Search Console: the date range with as of, the latest day Search Console has data for, which usually runs 2 to 3 days behind today. Then come the page’s impressions, clicks and average position, and its top 10 searches by impressions, with yes under THIS KEYWORD for this keyword’s searches. When the page has no figures to show, the section is one line instead: Google hasn’t shown the page in this range (no_impressions), the domain isn’t connected to Search Console (not_connected), Search Console needs reconnecting (needs_reconnect), the keyword has no page address (no_target_page), or the lookup failed (error). When Google doesn’t list the searches that only a few people made, the table and the showed this page line are replaced by one line saying so. A recommendation with the search_console source is a page of yours that Google showed for the keyword’s searches in the 28 days to page.windowEnd, a date a few days before today. It is only given when the keyword has no target and none of your pages ranks, and the line shows how many times Google showed it and the date the window ended. JSON fields: keyword, target, rankHistory, rankHistoryTruncated, prompts, recommendation, pageStatus, and searchPerformance. pageStatus holds the page status for the keyword (status, searchConsole, target, engines, rankHistory, rankHistoryTruncated, cited, citedAvailable, links). Each engine has indexed (true, false, or null) and indexInconclusive, which is true when indexed is null because the lookup couldn’t confirm. Each engine also has indexSource (search_console, search, or null), and indexReason, lastCrawledAt and googleCanonical. Every engine carries the last three. They are null for Bing and Brave, and for Google unless Search Console answered. searchConsole has a status of connected, needs_reconnect, or not_connected, and the connected property. citedAvailable is false when citations couldn’t be loaded or hit their row cap, so the page may be cited more than shown. pageStatus is null when the keyword is not targeted. searchPerformance has a state of ok, no_impressions, not_connected, needs_reconnect, no_target_page, or error. With ok it also has impressions, clicks, position (weighted by impressions), asOf, searches (each with keywordSearch), and keywordSearchCount. A failed lookup gives only "state": "error", and searchPerformance is left out for a keyword that is not targeted.

Show results

tpc query-bank results --scope pro-org/my-product
tpc query-bank results --from 2026-06-01 --to 2026-06-30 --scope pro-org/my-product

Compares share of voice before and after targeting, for targeted and other prompts, and lists each targeted keyword with its status and rank before and now.

Flag	Description
`--from`, `--to`	Date window, `YYYY-MM-DD`. Both required together. Defaults to the earliest target date across keywords through today, at most 180 days back.

Example output:

PRODUCT:	my-product
WINDOW:	2026-11-02 -> 2026-11-13

SHARE OF VOICE, targeted prompts:	not enough data
SHARE OF VOICE, other prompts:	not enough data

KEYWORD                    STATUS   RANK BEFORE  RANK NOW
best expense tracking app  ranking  not checked  4
expense report software    no_page  not checked  not in top 10

JSON is always { "comparison": ... }. comparison is null when nothing is targeted, or when a custom range ends before the first target date. Otherwise it holds from, to, defaultFrom, windows, sov, citedAvailable, and keywords (each with id, label, targetedAt, pageUrl, status, rankBefore, and rankNow). citedAvailable is false when citations couldn’t be loaded or hit their row cap, so a keyword whose status isn’t cited may still be cited. The text output then adds a CITATIONS: line.

Fields

pageStatus is null when the keyword is not targeted, and searchPerformance is left out. See how to read searchPerformance.
comparison is null when no keyword is targeted, or when a custom range ends before the first target date. Text output then prints (no targeted keywords yet).
status is one of no_page, not_checked, not_indexed, indexed, ranking, or cited, which means an AI engine cited or read the page in the date range. Claude, Sonar, and Perplexity only read pages. See what each status means.
In rankBefore and rankNow, null means no Google check covered the keyword by then, or the check that did has no search results for the keyword’s searches. A rank of null inside means it was checked and none of your pages is in the top 10. A rank is the best position of any of your pages for the keyword’s searches.
Share of voice values are fractions. Before and after run from 0 to 1. A change runs from -1 to 1 and is negative when that group’s share of voice fell. The difference is the targeted change minus the other change, runs from -2 to 2, and is negative when targeted prompts’ share of voice moved less than other prompts’, even if both rose.

The same data is available to your agent. See Which Query bank keywords should I work on next?.

Get started

Commands

Recipes

Reference

Query bank

Query bank

List keywords

Show a keyword

Show results

Fields