Competitor Keyword Research API - SpyFu SEO, PPC, Ad History

Pull competitor keyword research from the SpyFu API with your own API key: the organic keywords any domain ranks for, the PPC keywords it buys, its ad copy history, SEO and PPC competitors, top pages and monthly traffic stats, as clean dataset rows.

Works with the SpyFu API (api.spyfu.com), the API behind SpyFu's SEO Research, PPC Research, Competitors, Ad History, Keyword Research and Domain Overview tools. The actor turns a list of domains or keywords into deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into SEO dashboards, PPC audits, competitor reports, Google Sheets, Looker Studio and AI agents. Bring your own API key.

BYOK, not live-tested: every endpoint, parameter and enum comes from SpyFu's published OpenAPI reference at developer.spyfu.com, and every path was confirmed to exist with a deliberately invalid key, but the actor has not been run against a live SpyFu account.

What it does

• Domain organic keywords (SEO): the keywords a domain, subdomain, path or URL ranks for in Google, with rank, rank change, ranking URL, search volume, keyword difficulty, CPC, estimated SEO clicks and click share. Pick the analysis: most valuable, newly ranked, gained or lost ranks, gained or lost clicks, just made page one or just fell off. Add a compare domain to see its rank on the same keywords.
• Most successful PPC keywords and New PPC keywords: the Google Ads keywords a domain has bought most successfully over the past year, or started buying recently, with volume, CPC by match type, monthly cost, clicks and the other advertisers.
• Paid search ads for a domain: the ads a domain shows, with keyword, ad position, ad title and body, advertiser count and the date seen.
• Organic SEO competitors and PPC competitors: the domains sharing a domain's organic or paid keywords, with common keyword counts.
• Top organic pages: the pages that earn the most organic traffic, or new pages gaining traffic, with keyword count, estimated clicks and top keyword.
• Domain SEO and PPC stats: the latest month, or the last N months, of organic keywords, organic clicks and value, paid clicks, ad budget, ads purchased, average ranks and domain strength. Domain stats history returns every month SpyFu has tracked.
• Domain ad history and Keyword ad history: historical ad copy for an advertiser, or the advertisers and ads a keyword has carried, with position and date.
• Keyword research: phrase match, questions, also buys ads for, also ranks for, or transactional keywords for a seed keyword.
• Keyword metrics: search volume, live search volume, ranking difficulty, CPC and monthly cost by match type, click shares, SERP features and the first organic result for a keyword list.
• Keyword SERP top 100: the Google organic results for a keyword with rank, rank change, URL, title and domain.
• 28 Google countries, from US, UK, DE and AU to JP, IN, BR and ZA.
• Pay only for results: refused and empty lookups are recorded as a free row that says why, never charged.

How to get an API key

SpyFu includes API access with its Pro + AI plan (with a 40 USD monthly API credit) and its Team/Agency plan (100 USD monthly credit). Open your SpyFu account settings at spyfu.com/account/api (API Usage) and copy the Secret Key, not the API ID, into the API key field, or set the DATA_API_KEY environment secret. The actor sends it as the documented api_key query parameter. This actor never ships a shared key.

What a run costs at SpyFu

SpyFu bills per row returned, as a CPM per endpoint: 0.20 USD per 1,000 rows for competitors and keyword metrics, 0.40 to 0.50 USD for domain stats and SEO keywords and SERPs, 1.00 USD for keyword research, 2.00 USD for PPC keywords and paid ads, 3.00 USD for ad history and 5.00 USD for top pages. The monthly API credit is used first and the rest is billed to your card. maxResults caps both the rows here and the rows SpyFu bills, and every page asks only for the rows the run still needs.

Input

Field	Used by	What it does
mode	all	seoKeywords, ppcKeywords, newPpcKeywords, domainAds, seoCompetitors, ppcCompetitors, topPages, domainStats, domainStatsHistory, domainAdHistory, keywordResearch, keywordMetrics, keywordSerp or keywordAdHistory
domains	domain modes	Domains, one per line, such as nike.com (SEO keywords, PPC keywords and top pages also take a URL or path)
keywords	keyword modes	Keywords, one per line, such as running shoes
countryCode	all	Google country: US (default), UK, DE, AU and 24 more
seoSearchType	domain organic keywords	MostValuable (default), NewlyRanked, GainedRanks, LostRanks, GainedClicks, LostClicks, JustMadeIt, JustFellOff
compareDomain	domain organic keywords	A second domain whose rank is added to each row
topPagesType	top pages	MostTraffic (default) or New
keywordSearchType	keyword research	PhraseMatch (default), Questions, AlsoBuysAdsFor, AlsoRanksFor, Transactions
historyMonths	domain stats	0 for the latest month, or the number of recent months
keywordFilter	top pages, domain ad history	Keyword contains this text
serpDepth	keyword SERP	Results per keyword, 1 to 105 (default 100)
includeTerms, matchAnyTerm, excludeTerms	keyword lists	Terms a keyword must contain (all, or any) or must not contain
volumeMin, volumeMax, difficultyMin, difficultyMax	keyword lists, keyword metrics	Search volume and ranking difficulty ranges
cpcMin, cpcMax, cpcMatchType	SEO and PPC keywords, keyword research, keyword metrics	Cost per click range, by Broad, Exact or Phrase match
rankMin, rankMax	domain organic keywords	Google rank range, such as 1 to 10 for page one
excludeHomepageKeywords	SEO keywords, paid ads	Leave out keywords the homepage ranks for
questionsOnly, transactionalOnly	PPC keywords, keyword research, keyword metrics	Question or buying intent keywords only
includeAdult	keyword lists	Keep adult keywords, which SpyFu leaves out by default
seoSortBy, keywordSortBy, adSortBy, competitorSortBy, adHistorySortBy, sortOrder	list modes	Sort field and order
maxResults	all	Row ceiling for the run (default 100)
requestsPerMinute	all	Pacing (default 120)
apiKey	all	Your SpyFu Secret Key, stored as a secret

An endpoint only receives the parameters its documentation lists; an input that belongs to another mode is left off with a warning.

Example input, the page one keywords a competitor gained clicks on in the US, with your own rank alongside:

{
    "mode": "seoKeywords",
    "domains": ["semrush.com"],
    "seoSearchType": "GainedClicks",
    "compareDomain": "spyfu.com",
    "countryCode": "US",
    "rankMax": 10,
    "volumeMin": 500,
    "excludeTerms": ["semrush"],
    "maxResults": 100
}

Example output

An example domain organic keyword row, shaped from SpyFu's documented response. The common columns come first; every field SpyFu returns follows unchanged.

{
    "mode": "seoKeywords",
    "modeLabel": "Domain organic keywords",
    "recordType": "seoKeyword",
    "identifier": "semrush.com",
    "found": true,
    "countryCode": "US",
    "domain": "semrush.com",
    "keyword": "keyword research tool",
    "url": "https://www.semrush.com/analytics/keywordmagic/",
    "title": null,
    "rank": 3,
    "searchVolume": 9900,
    "difficulty": 78,
    "cpc": 12.4,
    "seoClicks": 1210,
    "period": null,
    "retrievedAt": "2026-10-14T09:00:00.000Z",
    "note": null,
    "topRankedUrl": "https://www.semrush.com/analytics/keywordmagic/",
    "rankChange": 2,
    "keywordDifficulty": 78,
    "broadCostPerClick": 12.4,
    "phraseCostPerClick": 11.9,
    "exactCostPerClick": 10.6,
    "seoClicksChange": 340,
    "totalMonthlyClicks": 7100,
    "percentMobileSearches": 22.5,
    "percentDesktopSearches": 77.5,
    "percentNotClicked": 28.1,
    "percentPaidClicks": 9.4,
    "percentOrganicClicks": 62.5,
    "broadMonthlyCost": 4210.0,
    "phraseMonthlyCost": 3890.0,
    "exactMonthlyCost": 2950.0,
    "paidCompetitors": 14,
    "rankingHomepages": 6,
    "yourRank": 5,
    "yourRankChange": -1,
    "yourUrl": "https://www.spyfu.com/keyword-research"
}

PPC keyword and keyword research rows carry liveSearchVolume, rankingDifficulty, CPC, monthly clicks and monthly cost by match type, distinctCompetitors, serpFeaturesCsv and serpFirstResult; paid ad rows carry adPosition, adCount, title, bodyHtml and dateSearched; competitor rows carry domain, commonTerms and rank; top page rows carry keywordCount, estMonthlySeoClicks and the top keyword with its position; domain stats rows carry period (YYYY-MM) with monthlyOrganicClicks, monthlyOrganicValue, monthlyPaidClicks, monthlyBudget, totalOrganicResults, totalAdsPurchased, averageOrganicRank, averageAdRank and strength; ad history rows carry title, body, position, searchDateId and adId. cpc is the broad match cost per click and difficulty is SpyFu's keyword (ranking) difficulty.

FAQ

What is the SpyFu API?

SpyFu is a competitor research tool for SEO and Google Ads that has tracked organic rankings and paid ads since 2007 across 28 Google country versions. Its REST API at api.spyfu.com serves the same domain, keyword, competitor and ad history data as the SpyFu web app, billed per row returned.

Do I need my own SpyFu API key?

Yes. The actor calls SpyFu with your own Secret Key, and SpyFu bills the rows to your own account. A run without a key ends straight away with a message that says where to find it, and nothing is charged.

How do I find the keywords a competitor ranks for?

Use the domain organic keywords mode with the competitor in domains. Most valuable lists the keywords that bring it the most organic clicks; the other analyses show what it gained, lost or newly ranks for this month. Add rankMax: 10 for page one, or your own site in compareDomain to see where it outranks you.

How do I see a competitor's Google Ads keywords and ad copy?

Most successful PPC keywords lists the keywords it has bought longest and most profitably, New PPC keywords what it just started bidding on, Paid search ads the ads it shows now, and Domain ad history its ad copy over the years.

How do I find a site's competitors?

Organic SEO competitors and PPC competitors list the domains that share the most organic or paid keywords with it, with the number of common keywords, up to 550 per domain.

How do I get search volume, CPC and keyword difficulty for a keyword list?

Use the keyword metrics mode and paste the keywords into keywords, one per line. Each keyword becomes one row with search volume, ranking difficulty, CPC and monthly cost by match type and click shares. For new ideas, use keyword research with phrase match, questions, also ranks for or also buys ads for.

What do I pay?

Pay per result: 0.005 USD per keyword, competitor, top page or SERP row, 0.008 USD per paid ad or ad history row, and 0.01 USD per month of domain stats. Refused and empty lookups are never charged. SpyFu bills its own per row API charges to your SpyFu account separately.

What happens if my key is wrong or my plan has no API access?

A rejected key (HTTP 401, "Secret Key Invalid") or a plan without API access ends the run cleanly with a status message that explains what to change. Rate limits (HTTP 429) are waited out using SpyFu's Retry-After header. A domain or keyword SpyFu refuses becomes a free row with the API's own words, and the run moves on.

How deep can a list go?

SpyFu's keyword and ad lists page up to row 10,000 per domain or keyword, competitors up to 550, and the SERP up to 105 results. The actor pages automatically and stops at maxResults.

Pricing

Event	Price	Charged for
keyword-row	0.005 USD	Each organic or PPC keyword, competitor, top page or SERP result
ad-row	0.008 USD	Each paid search ad or historical ad
domain-stats-row	0.01 USD	Each month of domain SEO and PPC statistics

Keyword map

SpyFu API, competitor keyword research, competitor analysis API, PPC keywords, Google Ads competitor research, ad copy history, ad spy tool, SEO keywords API, organic keywords, keyword gap, domain overview, website traffic estimate, SEO competitors, PPC competitors, top pages, keyword research API, search volume, keyword difficulty, CPC data, SERP API, Google top 100, Semrush alternative, Ahrefs alternative.

Terms and data use

Use of SpyFu is governed by SpyFu's terms and conditions (spyfu.com/termsconditions). They allow you to download, store and archive information from the service for your own use, and say that without SpyFu's written consent you may not sell, publish, distribute or retransmit its content, display it on another website or service, or use an archive of it to operate an automated reporting system. Run this actor with your own key, for your own SEO and PPC research, keep the results for your own use, and ask SpyFu before you republish or resell the data. This actor is not affiliated with or endorsed by SpyFu.