list_search_terms

Review the Google Ads search terms report with filtering, sorting, and pagination.

                PURPOSE:
                List the actual search queries that triggered the account's Google Ads, so you can
                review wasteful or off-target terms and decide which ones to add to a negative
                keywords list. Mirrors the "Search Terms" library page in the Metadata UI.

                WHEN TO USE:
                - Investigate which queries are costing money without producing clicks or conversions
                - Find queries to add to a negative keywords list (pair with add_keywords_to_negative_lists)
                - Inspect search terms tied to a specific experiment or matched keyword
                - Sort by cost / clicks / conversions to surface the worst offenders

                FILTERS (all optional):
                - searchTerm: substring match on the search term text
                - experiment: experiment name substring match
                - keyword: matched keyword substring
                - matchType: array subset of [PHRASE, BROAD, EXACT, NEAR_EXACT, NEAR_PHRASE]
                - startDate / endDate: ISO-8601 timestamps (e.g. 2026-06-01T00:00:00.000Z).
                  The UI defaults to the last 30 days when both are omitted.

                PAGINATION & SORT:
                - page: 0-based (default 0)
                - size: rows per page (default 12, max 100)
                - sort: "<field>,<direction>". Sortable fields include searchTerm, matchType,
                  experiment, addedExcluded, keyword, impressions, clicks, ctr, averageCpc,
                  spent, conversions, costPerConversion. Direction is asc or desc.
                  Default: "clicks,desc".

                RESPONSE FORMAT:
                Returns a paginated response:
                {
                  "totalElements": 123,
                  "totalPages": 5,
                  "data": [
                    {
                      "id": "bGVhZCBnZW5lcmF0aW9uIGNhbmFkYQ",
                      "searchTerm": "lead generation canada",
                      "experiment": "MD_Experiment",
                      "experimentId": "179908",
                      "matchType": "PHRASE",
                      "keyword": "lead generation",
                      "addedExcluded": "Added",
                      "impressions": 200,
                      "clicks": 11,
                      "ctr": 5.5,
                      "averageCpc": 2.3,
                      "spent": 25.30,
                      "conversions": 0,
                      "costPerConversion": null
                    },
                    ...
                  ]
                }

                COMMON USE CASES:
                1. Top spenders with zero conversions in the last 30 days:
                   list_search_terms(sort="spent,desc")
                   then filter the response client-side for conversions == 0.

                2. Worst CTR among phrase matches:
                   list_search_terms(matchType=["PHRASE"], sort="ctr,asc")

                3. Search terms tied to a specific experiment:
                   list_search_terms(experiment="Q2 Brand Test")

                4. Date-bounded review:
                   list_search_terms(
                     startDate="2026-05-01T00:00:00.000Z",
                     endDate="2026-05-31T23:59:59.999Z",
                     sort="spent,desc"
                   )

                PARAMETERS:
                - searchTerm (string, optional): substring filter on the search term text.
                - experiment (string, optional): experiment name substring filter.
                - keyword (string, optional): matched keyword substring filter.
                - matchType (array of strings, optional): subset of
                  [PHRASE, BROAD, EXACT, NEAR_EXACT, NEAR_PHRASE].
                - startDate (string, optional): ISO-8601 timestamp lower bound.
                - endDate (string, optional): ISO-8601 timestamp upper bound.
                - page (integer, optional): 0-based page index (default 0).
                - size (integer, optional): rows per page (default 12).
                - sort (string, optional): "<field>,<direction>" (default "clicks,desc").

                CHANNEL SCOPE:
                BOTH search channels are supported: pass channel=MICROSOFT_ADS for Microsoft
                Ads (Bing) and channel=GOOGLE_ADS for Google. The two channels hold SEPARATE
                reports, so never substitute one channel for the other to get "close enough"
                results.