list_keywords

List and search keywords with filtering, sorting, and pagination options.

                PURPOSE:
                Retrieve a paginated list of keywords from the Metadata platform with advanced
                sorting and filtering capabilities. Optionally search by keyword name. Use this tool
                to discover, analyze, and export keyword data for campaign planning and optimization.

                WHEN TO USE:
                - Browse all available keywords in the account
                - Search for specific keywords by name
                - Find keyword variations and similar terms
                - Export keyword data with custom sorting
                - Analyze keyword metrics (search volume, bid prices)
                - Build keyword lists for campaign creation
                - Filter keywords by archived status
                - Compare keyword performance metrics

                KEY FEATURES:
                ✓ NAME SEARCH: Filter by keyword name for targeted searches (optional)
                ✓ PAGINATION: Use page and size parameters to navigate large datasets
                ✓ SORTING: Sort by search volume, bid prices, name, or modification date
                ✓ FILTERING: Include or exclude archived keywords
                ✓ PERFORMANCE DATA: Get avgMonthlySearches, lowerPageBid, higherPageBid metrics

                NAME SEARCH:
                The optional 'name' parameter supports:
                1. Single name (string): Searches for one keyword name
                   - "marketing" → Finds "digital marketing", "email marketing", "marketing automation"
                   - "seo" → Finds "SEO services", "SEO tools", "SEO analytics"
                   - "ppc" → Finds "PPC advertising", "PPC campaigns"

                2. Multiple names (array of strings): Searches for multiple keywords at once
                   - ["marketing", "seo", "ppc"] → Aggregates results from all three searches
                   - Makes separate API requests for each name and combines results
                   - Automatically deduplicates keywords by ID
                   - Returns all unique keywords matching any of the provided names

                - Omit 'name' parameter to list all keywords without filtering
                - Both single and multiple searches support partial matching

                PAGINATION STRATEGY:
                The API returns paginated results. Use these parameters to navigate:
                - page: 0-based page number (default: 0, meaning first page)
                - size: Number of results per page (default: 25, recommended: 25-100)

                To get the next page of results, increment the 'page' parameter.
                Example:
                - page=0, size=25 → Returns items 0-24
                - page=1, size=25 → Returns items 25-49
                - page=2, size=25 → Returns items 50-74

                SORT OPTIONS (use format: field,direction):
                Available fields for sorting:
                - avgMonthlySearches,desc/asc: Sort by average monthly search volume
                - lowerPageBid,desc/asc: Sort by lower page bid (CPC floor price)
                - higherPageBid,desc/asc: Sort by higher page bid (CPC ceiling price)
                - name,desc/asc: Sort by keyword name alphabetically
                - modifiedDate,desc/asc: Sort by Modification/Update date (default)

                Direction options:
                - desc: Descending order (highest to lowest)
                - asc: Ascending order (lowest to highest)

                SORT EXAMPLES:
                - sort="avgMonthlySearches,desc": Keywords with highest search volume first
                - sort="avgMonthlySearches,asc": Keywords with lowest search volume first
                - sort="lowerPageBid,desc": Keywords with highest CPC floor first
                - sort="higherPageBid,asc": Keywords with lowest CPC ceiling first
                - sort="name,asc": Keywords in alphabetical order (A-Z)
                - sort="name,desc": Keywords in reverse alphabetical order (Z-A)

                FILTERING:
                - archived: Filter by archived status (true/false, default: false)
                  Set to true to include archived keywords
                  Set to false to show only active keywords (recommended)

                PAGINATION WORKFLOW:
                1. Start with page=0 to get the first set of keywords
                2. Check the response metadata to see if more results exist
                3. If needed, increment page number and fetch again
                4. Continue until all desired results are retrieved

                RESPONSE FORMAT:
                Returns a paginated response with:
                {
                  "totalElements": 2,
                  "totalPages": 1,
                  "data": [
                    {
                      "name": "product match",
                      "avgMonthlySearches": 260,
                      "competition": "LOW",
                      "lowerPageBid": 0.00,
                      "higherPageBid": 0.00,
                      "id": 18330,
                      "archived": false,
                      "createdDate": "2025-09-15T20:35:50.000Z",
                      "modifiedDate": "2025-09-30T21:14:59.000Z"
                    },
                    {
                      "name": "keyword match",
                      "avgMonthlySearches": 140,
                      "competition": "LOW",
                      "lowerPageBid": 0.00,
                      "higherPageBid": 0.00,
                      "id": 18339,
                      "archived": false,
                      "createdDate": "2025-09-15T20:35:50.000Z",
                      "modifiedDate": "2025-09-30T21:14:59.000Z"
                    }
                  ]
                }

                COMMON USE CASES:
                1. List all active keywords:
                   list_keywords()

                2. Search for "marketing" keywords:
                   list_keywords(name="marketing")

                3. Get top 50 keywords by search volume:
                   list_keywords(page=0, size=50, sort="avgMonthlySearches,desc")

                4. Find expensive keywords (highest CPC) with name search:
                   list_keywords(name="analytics", sort="higherPageBid,desc")

                5. Find affordable keywords (lowest CPC):
                   list_keywords(sort="lowerPageBid,asc")

                6. Get alphabetically sorted active keywords:
                   list_keywords(page=0, size=100, sort="name,asc", archived=false)

                7. Export all keywords (paginate through results):
                   list_keywords(page=0, size=100)
                   list_keywords(page=1, size=100)
                   list_keywords(page=2, size=100)
                   ... (repeat for all pages shown in totalPages)

                8. Get recently modified keywords:
                   list_keywords(page=0, size=25, sort="modifiedDate,desc")

                9. Search with pagination:
                   list_keywords(name="marketing", page=0, size=50)
                   list_keywords(name="marketing", page=1, size=50)

                10. Search for multiple keyword names at once:
                    list_keywords(name=["marketing", "seo", "ppc"])

                11. Search multiple names with sorting:
                    list_keywords(name=["analytics", "ads"], sort="avgMonthlySearches,desc")

                12. Search multiple names and exclude archived:
                    list_keywords(name=["social", "media"], archived=false)

                PARAMETERS:
                - name: Optional keyword name or partial name to search for. Can be a string or array of strings.
                        Supports partial matching. Omit to list all keywords. (optional)
                - archived: Filter by archived status (default: false)
                - page: Page number for pagination (0-based, default: 0)
                - size: Number of items per page (default: 25, max recommended: 100)
                - sort: Sort criteria in format: field,direction (default: modifiedDate,desc)

                PERFORMANCE TIPS:
                - Use size=100 for bulk exports to reduce API calls
                - Use page number to efficiently navigate large datasets
                - Filter by archived=false to exclude inactive keywords
                - Sort by modifiedDate,desc to see recent changes
                - Use name parameter for targeted searches to reduce result set
                - When searching multiple names, each name triggers a separate API call
                  Use reasonable list sizes to avoid excessive API calls

                EXAMPLES:
                - list_keywords() - Get first 25 active keywords
                - list_keywords(name="marketing") - Search for marketing keywords
                - list_keywords(name=["marketing", "seo"]) - Search multiple keywords
                - list_keywords(page=0, size=50, sort="avgMonthlySearches,desc") - Top 50 by search volume
                - list_keywords(name="seo", sort="avgMonthlySearches,desc") - SEO keywords by search volume
                - list_keywords(name=["ads", "analytics"], sort="higherPageBid,desc") - Multiple names by bid price
                - list_keywords(page=1, size=100, archived=false, sort="name,asc") - Page 2 of keywords A-Z
                - list_keywords(page=0, size=25, sort="lowerPageBid,desc") - Most expensive keywords