Skip to main content

Documentation Index

Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

SEO is the primitive that gives your agent access to comprehensive search engine optimization data. Naive wraps three core SEO APIs — Keywords Data, Backlinks, and SEO Labs — so agents can research keywords, audit backlink profiles, and analyze competitors programmatically. Every live keyword endpoint also supports the Standard (async) method for batch workflows.

CLI First

# Google keyword volume
naive seo keywords google search-volume --keywords "ai tools,chatbot software" --location-code 2840

# Backlink summary
naive seo backlinks summary --target example.com

# Labs keyword overview
naive seo labs google keyword-overview --keywords "project management software" --location-code 2840

Sub-APIs

APITypeDescriptionSpeedCost
Keywords Data — GoogleCoreSearch volume, keyword suggestions, ad traffic via Google AdsFast (~2s)1 credit
Keywords Data — BingCoreSearch volume, keyword suggestions, keyword performance via BingFast (~2s)1 credit
Keywords Data — Google TrendsCoreTrend exploration for keywords over timeFast (~2s)1 credit
BacklinksCoreBacklink profiles, referring domains, anchor texts, competitor analysisFast (~2-5s)2 credits
Backlinks — BulkCoreBulk backlink counts, ranks, spam scores for up to 1000 targetsFast (~3-8s)5 credits
SEO Labs — GoogleCoreKeyword research, SERP analysis, competitor insights from Google dataFast (~2-5s)2 credits
SEO Labs — BingCoreKeyword and competitor research from Bing dataFast (~2-5s)2 credits
SEO Labs — AmazonCoreProduct keyword research and competitor analysis on AmazonFast (~2-5s)2 credits
Labs — BulkCoreBulk keyword difficulty, bulk traffic estimationFast (~3-8s)5 credits
Meta / UtilityUtilityLocations, languages, categories, statusFast (~1s)Free

Quick Examples

# Google keyword search volume (live)
curl -X POST https://api.usenaive.ai/v1/seo/keywords/google/search-volume \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["ai tools", "chatbot software"], "location_code": 2840 }'

# Backlink summary
curl -X POST https://api.usenaive.ai/v1/seo/backlinks/summary \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "target": "example.com" }'

# Labs keyword overview
curl -X POST https://api.usenaive.ai/v1/seo/labs/google/keyword-overview \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["project management software"], "location_code": 2840 }'

Keywords Data API

Keywords Data provides search volume, keyword suggestions, and ad traffic estimates across Google, Bing, and Google Trends. Each data endpoint supports both Live (instant results via POST) and Standard (async task via POST + GET) modes.

Google Endpoints

EndpointRouteMethodDescription
search-volumePOST /v1/seo/keywords/google/search-volumeLive + StandardMonthly search volume, CPC, competition for up to 1000 keywords
keywords-for-keywordsPOST /v1/seo/keywords/google/keywords-for-keywordsLive + StandardRelated keywords based on seed keywords
keywords-for-sitePOST /v1/seo/keywords/google/keywords-for-siteLive + StandardKeywords a domain ranks for in Google Ads
keywords-for-categoryPOST /v1/seo/keywords/google/keywords-for-categoryLive + StandardKeywords for a Google Ads category
ad-traffic-by-keywordsPOST /v1/seo/keywords/google/ad-traffic-by-keywordsLive + StandardEstimated ad traffic and CPC for keywords
ad-traffic-by-platformsPOST /v1/seo/keywords/google/ad-traffic-by-platformsLive + StandardAd traffic broken down by platform (mobile, desktop, tablet)

Google Meta Endpoints

EndpointRouteMethodDescription
locationsGET /v1/seo/keywords/google/locationsGETValid location codes for Google
languagesGET /v1/seo/keywords/google/languagesGETValid language codes for Google
categoriesGET /v1/seo/keywords/google/categoriesGETGoogle Ads category list
adwords-statusGET /v1/seo/keywords/google/adwords-statusGETGoogle Ads API availability status

Bing Endpoints

EndpointRouteMethodDescription
search-volumePOST /v1/seo/keywords/bing/search-volumeLive + StandardBing monthly search volume, CPC, competition
keywords-for-keywordsPOST /v1/seo/keywords/bing/keywords-for-keywordsLive + StandardRelated keywords from Bing data
keywords-for-sitePOST /v1/seo/keywords/bing/keywords-for-siteLive + StandardKeywords a domain ranks for in Bing Ads
keywords-for-categoryPOST /v1/seo/keywords/bing/keywords-for-categoryLive + StandardKeywords for a Bing Ads category
keyword-performancePOST /v1/seo/keywords/bing/keyword-performanceLive + StandardHistorical keyword performance data in Bing

Bing Meta Endpoints

EndpointRouteMethodDescription
locationsGET /v1/seo/keywords/bing/locationsGETValid location codes for Bing
languagesGET /v1/seo/keywords/bing/languagesGETValid language codes for Bing
categoriesGET /v1/seo/keywords/bing/categoriesGETBing Ads category list
EndpointRouteMethodDescription
explorePOST /v1/seo/keywords/google-trends/exploreLive + StandardTrend data for keywords over time and by region
EndpointRouteMethodDescription
locationsGET /v1/seo/keywords/google-trends/locationsGETValid location codes for Google Trends
languagesGET /v1/seo/keywords/google-trends/languagesGETValid language codes for Google Trends
categoriesGET /v1/seo/keywords/google-trends/categoriesGETGoogle Trends category list

Utility

EndpointRouteMethodDescription
endpointsGET /v1/seo/keywords/endpointsGETList all available Keywords Data API endpoints

Live vs Standard Mode

Every data endpoint (not meta) supports two modes:
  • LivePOST /v1/seo/keywords/{engine}/{endpoint} — instant results in the response body.
  • Standard — submit via POST .../task, check readiness via GET .../tasks-ready, retrieve via GET .../task/:id.
# Live: instant results
curl -X POST https://api.usenaive.ai/v1/seo/keywords/google/search-volume \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["ai tools", "chatbot software"], "location_code": 2840, "language_code": "en" }'

# Standard: submit task
curl -X POST https://api.usenaive.ai/v1/seo/keywords/google/search-volume/task \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["ai tools", "chatbot software"], "location_code": 2840 }'

# Standard: retrieve results
curl -G https://api.usenaive.ai/v1/seo/keywords/google/search-volume/task/TASK_ID \
  -H "Authorization: Bearer nv_sk_your_key"
Response (Live — search-volume):
{
  "results": [
    {
      "keyword": "ai tools",
      "search_volume": 165000,
      "competition": 0.87,
      "competition_level": "HIGH",
      "cpc": 4.32,
      "monthly_searches": [
        { "year": 2026, "month": 4, "search_volume": 165000 },
        { "year": 2026, "month": 3, "search_volume": 148000 }
      ]
    },
    {
      "keyword": "chatbot software",
      "search_volume": 22200,
      "competition": 0.74,
      "competition_level": "HIGH",
      "cpc": 8.15,
      "monthly_searches": [
        { "year": 2026, "month": 4, "search_volume": 22200 },
        { "year": 2026, "month": 3, "search_volume": 20100 }
      ]
    }
  ],
  "credits_used": 1
}

Parameters

ParamTypeRequiredDefaultDescription
keywordsstring[]YesKeywords to analyze (max varies by endpoint, typically 1000)
location_codenumberNoLocation code (e.g. 2840 for US)
language_codestringNoLanguage code (e.g. “en”)
date_fromstringNoStart date for historical data (YYYY-MM-DD)
date_tostringNoEnd date for historical data (YYYY-MM-DD)
sort_bystringNoSort field (varies by endpoint)
limitnumberNoMax results to return
offsetnumberNo0Pagination offset

When to use

  • Estimating keyword search volume before creating content
  • Discovering related keywords for topic clusters
  • Analyzing ad traffic and CPC for paid campaigns
  • Tracking keyword trends over time via Google Trends
  • Comparing keyword performance across Google and Bing
  • Finding keywords competitors are buying ads for

The Backlinks API provides instant backlink profile data — referring domains, anchor texts, competitors, and bulk analysis. All endpoints use the Live method (instant POST results).

Live POST Endpoints

EndpointRouteDescription
summaryPOST /v1/seo/backlinks/summaryComplete backlink profile overview
historyPOST /v1/seo/backlinks/historyHistorical backlink count over time
backlinksPOST /v1/seo/backlinks/backlinksDetailed list of individual backlinks
anchorsPOST /v1/seo/backlinks/anchorsAnchor text distribution and stats
domain-pagesPOST /v1/seo/backlinks/domain-pagesPages on the target domain with backlinks
domain-pages-summaryPOST /v1/seo/backlinks/domain-pages-summarySummary stats for domain pages
referring-domainsPOST /v1/seo/backlinks/referring-domainsBreakdown of referring domains
referring-networksPOST /v1/seo/backlinks/referring-networksReferring network (IP/subnet) analysis
competitorsPOST /v1/seo/backlinks/competitorsSites sharing your backlink profile
domain-intersectionPOST /v1/seo/backlinks/domain-intersectionDomains linking to multiple targets
page-intersectionPOST /v1/seo/backlinks/page-intersectionPages linking to multiple targets
timeseries-summaryPOST /v1/seo/backlinks/timeseries-summaryTime-series backlink metrics
timeseries-new-lostPOST /v1/seo/backlinks/timeseries-new-lostNew and lost backlinks over time
bulk-backlinksPOST /v1/seo/backlinks/bulk-backlinksBacklink counts for up to 1000 targets
bulk-referring-domainsPOST /v1/seo/backlinks/bulk-referring-domainsReferring domain counts in bulk
bulk-ranksPOST /v1/seo/backlinks/bulk-ranksDomain/page rank scores in bulk
bulk-spam-scorePOST /v1/seo/backlinks/bulk-spam-scoreSpam scores for multiple targets
bulk-new-lostPOST /v1/seo/backlinks/bulk-new-lostNew/lost backlink counts in bulk
bulk-pages-summaryPOST /v1/seo/backlinks/bulk-pages-summaryPage-level summary in bulk

GET Endpoints

EndpointRouteDescription
indexGET /v1/seo/backlinks/indexCurrent backlink index size and freshness
available-filtersGET /v1/seo/backlinks/available-filtersList of available filter fields

Other

EndpointRouteMethodDescription
id-listPOST /v1/seo/backlinks/id-listPOSTList task IDs with status information
# Backlink summary for a domain
curl -X POST https://api.usenaive.ai/v1/seo/backlinks/summary \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "target": "example.com", "mode": "as_is" }'

# Bulk spam scores
curl -X POST https://api.usenaive.ai/v1/seo/backlinks/bulk-spam-score \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "targets": ["example.com", "competitor.com", "another.com"] }'
Response (summary):
{
  "results": [
    {
      "target": "example.com",
      "total_backlinks": 284530,
      "total_referring_domains": 12847,
      "total_referring_main_domains": 8421,
      "total_referring_ips": 9103,
      "total_referring_subnets": 7842,
      "nofollow_backlinks": 98200,
      "dofollow_backlinks": 186330,
      "spam_score": 12,
      "rank": 482,
      "broken_backlinks": 3240,
      "first_seen": "2018-03-15",
      "last_visited": "2026-05-01"
    }
  ],
  "credits_used": 2
}

Parameters

ParamTypeRequiredDefaultDescription
targetstringYesDomain or URL to analyze
targetsstring[]Yes (bulk)Multiple domains/URLs for bulk endpoints (max 1000)
limitnumberNo100Max results to return
offsetnumberNo0Pagination offset
modestringNo”as_is”Target matching: as_is, one_per_domain, one_per_anchor
filtersarrayNoFilter conditions (see available-filters endpoint)
order_byarrayNoSort order for results
backlinks_status_typestringNo”all”Filter by status: all, live, lost

When to use

  • Auditing your own backlink profile for toxic links
  • Analyzing competitor link-building strategies
  • Finding link prospects via domain/page intersection
  • Bulk-checking spam scores for link cleanup campaigns
  • Tracking new/lost backlinks over time
  • Comparing referring domain counts across competitors

SEO Labs API

Labs endpoints provide keyword research, competitor analysis, and SERP insights using a proprietary SEO database. All use the Live method — instant POST results. Available for Google, Bing, and Amazon.

Google Endpoints (23)

EndpointRouteDescription
keywords-for-sitePOST /v1/seo/labs/google/keywords-for-siteKeywords a domain ranks for organically
related-keywordsPOST /v1/seo/labs/google/related-keywordsSemantically related keywords
keyword-suggestionsPOST /v1/seo/labs/google/keyword-suggestionsKeyword ideas based on a seed keyword
keyword-ideasPOST /v1/seo/labs/google/keyword-ideasBroad keyword ideas from multiple seeds
bulk-keyword-difficultyPOST /v1/seo/labs/google/bulk-keyword-difficultyDifficulty scores for up to 1000 keywords
search-intentPOST /v1/seo/labs/google/search-intentClassify keyword intent (informational, transactional, etc.)
keyword-overviewPOST /v1/seo/labs/google/keyword-overviewComprehensive keyword metrics overview
historical-keyword-dataPOST /v1/seo/labs/google/historical-keyword-dataHistorical search volume and metrics
categories-for-domainPOST /v1/seo/labs/google/categories-for-domainCategories a domain is associated with
keywords-for-categoriesPOST /v1/seo/labs/google/keywords-for-categoriesKeywords for specific categories
domain-metrics-by-categoriesPOST /v1/seo/labs/google/domain-metrics-by-categoriesDomain performance by category
top-searchesPOST /v1/seo/labs/google/top-searchesTrending and top search queries
ranked-keywordsPOST /v1/seo/labs/google/ranked-keywordsKeywords a domain currently ranks for
serp-competitorsPOST /v1/seo/labs/google/serp-competitorsDomains competing in SERPs for given keywords
competitors-domainPOST /v1/seo/labs/google/competitors-domainCompetitor domains based on keyword overlap
domain-intersectionPOST /v1/seo/labs/google/domain-intersectionKeywords shared between multiple domains
subdomainsPOST /v1/seo/labs/google/subdomainsSubdomains with organic rankings
relevant-pagesPOST /v1/seo/labs/google/relevant-pagesTop-ranking pages for a domain
domain-rank-overviewPOST /v1/seo/labs/google/domain-rank-overviewDomain authority, traffic, and ranking summary
historical-serpsPOST /v1/seo/labs/google/historical-serpsHistorical SERP snapshots for keywords
historical-rank-overviewPOST /v1/seo/labs/google/historical-rank-overviewHistorical rank tracking for a domain
page-intersectionPOST /v1/seo/labs/google/page-intersectionKeywords shared between specific pages
bulk-traffic-estimationPOST /v1/seo/labs/google/bulk-traffic-estimationTraffic estimates for multiple domains

Bing Endpoints (11)

EndpointRouteDescription
related-keywordsPOST /v1/seo/labs/bing/related-keywordsSemantically related keywords from Bing data
ranked-keywordsPOST /v1/seo/labs/bing/ranked-keywordsKeywords a domain ranks for in Bing
domain-rank-overviewPOST /v1/seo/labs/bing/domain-rank-overviewDomain authority and ranking summary for Bing
serp-competitorsPOST /v1/seo/labs/bing/serp-competitorsSERP competitors in Bing results
domain-intersectionPOST /v1/seo/labs/bing/domain-intersectionKeywords shared between domains in Bing
page-intersectionPOST /v1/seo/labs/bing/page-intersectionKeywords shared between pages in Bing
relevant-pagesPOST /v1/seo/labs/bing/relevant-pagesTop-ranking pages in Bing
competitors-domainPOST /v1/seo/labs/bing/competitors-domainCompetitor domains in Bing
subdomainsPOST /v1/seo/labs/bing/subdomainsSubdomains with Bing rankings
bulk-keyword-difficultyPOST /v1/seo/labs/bing/bulk-keyword-difficultyBulk keyword difficulty for Bing
bulk-traffic-estimationPOST /v1/seo/labs/bing/bulk-traffic-estimationBulk traffic estimates from Bing data

Amazon Endpoints (6)

EndpointRouteDescription
bulk-search-volumePOST /v1/seo/labs/amazon/bulk-search-volumeSearch volume for keywords on Amazon
related-keywordsPOST /v1/seo/labs/amazon/related-keywordsRelated keywords on Amazon
ranked-keywordsPOST /v1/seo/labs/amazon/ranked-keywordsKeywords a product ranks for on Amazon
product-rank-overviewPOST /v1/seo/labs/amazon/product-rank-overviewProduct ranking overview on Amazon
product-competitorsPOST /v1/seo/labs/amazon/product-competitorsCompeting products on Amazon
product-keyword-intersectionsPOST /v1/seo/labs/amazon/product-keyword-intersectionsKeywords shared between Amazon products

Utility GET Endpoints

EndpointRouteDescription
locations-and-languagesGET /v1/seo/labs/locations-and-languagesValid location + language pairs for Labs
categoriesGET /v1/seo/labs/categoriesSEO Labs category list
statusGET /v1/seo/labs/statusLabs API availability status
# Keyword overview
curl -X POST https://api.usenaive.ai/v1/seo/labs/google/keyword-overview \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["project management software"],
    "location_code": 2840,
    "language_code": "en"
  }'

# Domain rank overview
curl -X POST https://api.usenaive.ai/v1/seo/labs/google/domain-rank-overview \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "target": "notion.so", "location_code": 2840 }'

# Amazon product competitors
curl -X POST https://api.usenaive.ai/v1/seo/labs/amazon/product-competitors \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "asin": "B09V3KXJPB", "location_code": 2840 }'
Response (keyword-overview):
{
  "results": [
    {
      "keyword": "project management software",
      "search_volume": 74000,
      "keyword_difficulty": 82,
      "cpc": 12.45,
      "competition_level": "HIGH",
      "search_intent": "commercial",
      "serp_info": {
        "featured_snippet": true,
        "knowledge_panel": false,
        "local_pack": false,
        "top_stories": false
      },
      "avg_backlinks_top_10": 1240,
      "avg_domain_rating_top_10": 78
    }
  ],
  "credits_used": 2
}

Parameters

ParamTypeRequiredDefaultDescription
keywordsstring[]VariesKeywords to analyze
keywordstringVariesSingle seed keyword (for suggestion endpoints)
targetstringVariesTarget domain or URL
targetsstring[]VariesMultiple domains for intersection/bulk endpoints
asinstringVariesAmazon product ASIN (Amazon endpoints only)
location_codenumberNoLocation code
language_codestringNoLanguage code
limitnumberNo100Max results to return
offsetnumberNo0Pagination offset
filtersarrayNoFilter conditions
order_byarrayNoSort order

When to use

  • Getting keyword difficulty scores before targeting terms
  • Finding competitor keywords you’re missing (domain-intersection)
  • Analyzing SERP competition for specific terms
  • Estimating traffic potential for domains in bulk
  • Classifying search intent for content strategy
  • Researching Amazon product keyword opportunities

Credit Costs

CategoryEndpointsCost
Keywords Data — LiveAll Google, Bing, Google Trends data endpoints1 credit
Keywords Data — Standard (task)All Google, Bing, Google Trends data endpoints via task workflow1 credit
Backlinks — Standardsummary, history, backlinks, anchors, domain-pages, domain-pages-summary, referring-domains, referring-networks, competitors, domain-intersection, page-intersection, timeseries-summary, timeseries-new-lost2 credits
Backlinks — Bulkbulk-backlinks, bulk-referring-domains, bulk-ranks, bulk-spam-score, bulk-new-lost, bulk-pages-summary5 credits
Labs — StandardAll Google (23), Bing (11), Amazon (6) endpoints except bulk2 credits
Labs — Bulkbulk-keyword-difficulty, bulk-traffic-estimation, bulk-search-volume5 credits
Meta / Utilitylocations, languages, categories, adwords-status, endpoints, status, available-filters, index, locations-and-languagesFree

Error Handling

ErrorCauseRecovery
insufficient_creditsNot enough credits for the operationCheck balance with GET /v1/status
invalid_locationUnknown location codeUse GET /v1/seo/keywords/google/locations to find valid codes
invalid_keywordsEmpty or malformed keyword listProvide at least one keyword string
invalid_targetMissing or malformed target domain/URLProvide a valid domain (e.g. “example.com”) or full URL
too_many_targetsExceeded max targets for bulk endpointReduce to 1000 targets or fewer
provider_errorSEO data provider returned an errorRetry after a few seconds
Use the naive_seo_discover MCP tool to find the right endpoint for your use case — it supports natural language filtering across all 90+ SEO endpoints.

Typical Workflow

Agent receives task: "Find keyword opportunities for our blog"

    ├─ POST /v1/seo/keywords/google/search-volume         → Check current volumes
    │   { keywords: ["ai agents", "llm tools"] }
    │   → Volume, CPC, competition data

    ├─ POST /v1/seo/labs/google/keyword-suggestions        → Expand keyword list
    │   { keyword: "ai agents", location_code: 2840 }
    │   → Related keywords with difficulty scores

    ├─ POST /v1/seo/labs/google/search-intent              → Classify intent
    │   { keywords: ["ai agents", "buy ai agent"] }
    │   → informational, commercial, transactional labels

    ├─ POST /v1/seo/labs/google/serp-competitors           → Analyze competition
    │   { keywords: ["ai agents"], location_code: 2840 }
    │   → Top-ranking domains and their metrics

    ├─ POST /v1/seo/labs/google/domain-intersection        → Find gaps
    │   { targets: ["yourdomain.com", "competitor.com"] }
    │   → Keywords competitor ranks for that you don't

    └─ POST /v1/seo/backlinks/summary                      → Audit competitor links
        { target: "competitor.com" }
        → Backlink count, referring domains, spam score