# Research
Keyword and competitor research
## Research keyword opportunities
> Get keyword ideas from seed keywords using DataForSEO. Returns search volume, difficulty, and intent data.\
> Requires Power plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/keywords":{"post":{"summary":"Research keyword opportunities","description":"Get keyword ideas from seed keywords using DataForSEO. Returns search volume, difficulty, and intent data.\nRequires Power plan or higher.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seed_keywords"],"properties":{"seed_keywords":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Seed keywords to research"},"location":{"type":"string","default":"United States"},"language":{"type":"string","default":"en"},"include_questions":{"type":"boolean","default":true},"limit":{"type":"number","minimum":1,"maximum":500,"default":50}}}}}},"responses":{"200":{"description":"Keyword research results","content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"search_volume":{"type":"number"},"keyword_difficulty":{"type":"number"},"cpc":{"type":"number"},"competition":{"type":"string"},"search_intent":{"type":"string"},"is_question":{"type":"boolean"}}}},"total":{"type":"number"},"seed_keywords":{"type":"array","items":{"type":"string"}},"location":{"type":"string"}}}}}}},"tags":["Research"]}}}}
```
## Analyze SERP for a keyword
> Get detailed SERP analysis including organic results, SERP features, People Also Ask, and search intent.\
> Requires Power plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/serp":{"post":{"summary":"Analyze SERP for a keyword","description":"Get detailed SERP analysis including organic results, SERP features, People Also Ask, and search intent.\nRequires Power plan or higher.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string","maxLength":200},"location":{"type":"string","default":"United States"},"language":{"type":"string","default":"en"}}}}}},"responses":{"200":{"description":"SERP analysis results","content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string"},"location":{"type":"string"},"search_intent":{"type":"string","enum":["informational","commercial","transactional","local"]},"difficulty":{"type":"string","enum":["Low","Medium","High"]},"serp_features":{"type":"array","items":{"type":"string"}},"organic_results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"url":{"type":"string"},"title":{"type":"string"},"domain":{"type":"string"}}}},"people_also_ask":{"type":"array","items":{"type":"string"}},"unique_domains":{"type":"number"}}}}}}},"tags":["Research"]}}}}
```
## Analyze competitor keywords
> Get keywords that a competitor domain ranks for. Useful for competitive analysis and content gap identification.\
> Requires Power plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/competitors":{"post":{"summary":"Analyze competitor keywords","description":"Get keywords that a competitor domain ranks for. Useful for competitive analysis and content gap identification.\nRequires Power plan or higher.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Competitor domain to analyze (e.g., \"competitor.com\")"},"location":{"type":"string","default":"United States"},"limit":{"type":"number","minimum":1,"maximum":200,"default":50}}}}}},"responses":{"200":{"description":"Competitor keyword analysis","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"keywords":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"search_volume":{"type":"number"},"keyword_difficulty":{"type":"number"},"cpc":{"type":"number"},"competition":{"type":"string"}}}},"total":{"type":"number"},"total_volume":{"type":"number"},"competition_breakdown":{"type":"object","additionalProperties":{"type":"number"}}}}}}}},"tags":["Research"]}}}}
```
## Google Trends data
> Get Google Trends data for keywords: popularity over time, rising topics, breakout queries, and trend direction.\
> Useful for validating content ideas, finding trending topics, and discovering what people are searching for.\
> Supports web, news, YouTube, and image search types.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/trends":{"post":{"summary":"Google Trends data","description":"Get Google Trends data for keywords: popularity over time, rising topics, breakout queries, and trend direction.\nUseful for validating content ideas, finding trending topics, and discovering what people are searching for.\nSupports web, news, YouTube, and image search types.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keywords"],"properties":{"keywords":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":5,"description":"Keywords to check trends for (max 5)"},"location":{"type":"string","description":"Location name (e.g. \"United States\")"},"time_range":{"type":"string","enum":["past_hour","past_4_hours","past_day","past_7_days","past_30_days","past_90_days","past_12_months","past_5_years"],"default":"past_12_months","description":"Time range for trend data"},"type":{"type":"string","enum":["web","news","youtube","images"],"default":"web","description":"Search type"}}}}}},"responses":{"200":{"description":"Trend data with direction, related topics, and rising queries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"location":{"type":"string"},"timeRange":{"type":"string"},"searchType":{"type":"string"},"items":{"type":"array","items":{"type":"object"}}}}}}}}}},"tags":["Research"]}}}}
```
## Web search via Perplexity
> Search the web for real-time information using Perplexity Sonar Pro.\
> Returns a structured analysis with citations. Use for trending social media topics,\
> industry news, competitor activity, viral content formats, or any question requiring current information.\
> Requires a Perplexity API key in team settings.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/web-search":{"post":{"summary":"Web search via Perplexity","description":"Search the web for real-time information using Perplexity Sonar Pro.\nReturns a structured analysis with citations. Use for trending social media topics,\nindustry news, competitor activity, viral content formats, or any question requiring current information.\nRequires a Perplexity API key in team settings.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"Search query for web research"},"focus":{"type":"string","enum":["general","social_trends","industry_news","competitor_analysis"],"default":"general","description":"Focus area to refine the search context"}}}}}},"responses":{"200":{"description":"Structured research result with citations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"focus":{"type":"string"},"result":{"type":"string","description":"Structured analysis text"},"citations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object","properties":{"promptTokens":{"type":"integer"},"completionTokens":{"type":"integer"}}}}}}}}}}},"tags":["Research"]}}}}
```
## Cluster keywords by intent and topic
> Group keywords by search intent (informational, commercial, transactional, navigational) and topic clusters.\
> Useful for content planning and site architecture.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/cluster":{"post":{"summary":"Cluster keywords by intent and topic","description":"Group keywords by search intent (informational, commercial, transactional, navigational) and topic clusters.\nUseful for content planning and site architecture.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keywords"],"properties":{"keywords":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500},"method":{"type":"string","enum":["intent","topic","both"],"default":"both"}}}}}},"responses":{"200":{"description":"Keyword clustering results","content":{"application/json":{"schema":{"type":"object","properties":{"intent_clusters":{"type":"object","properties":{"informational":{"type":"array","items":{"type":"string"}},"commercial":{"type":"array","items":{"type":"string"}},"transactional":{"type":"array","items":{"type":"string"}},"navigational":{"type":"array","items":{"type":"string"}}}},"topic_clusters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"count":{"type":"number"}}}},"total_keywords":{"type":"number"},"method":{"type":"string"}}}}}}},"tags":["Research"]}}}}
```
## Bulk SERP clustering with site assignment
> Submit a large batch of keywords (15K-60K) for SERP-based clustering and automatic site assignment.\
> Keywords are clustered by URL overlap, then assigned to sites based on category matching from an Airtable source.\
> Results are written to an Airtable output table.\
> \
> This is an async operation. Use the returned job\_id to poll for status.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/serp-cluster-bulk":{"post":{"summary":"Bulk SERP clustering with site assignment","description":"Submit a large batch of keywords (15K-60K) for SERP-based clustering and automatic site assignment.\nKeywords are clustered by URL overlap, then assigned to sites based on category matching from an Airtable source.\nResults are written to an Airtable output table.\n\nThis is an async operation. Use the returned job_id to poll for status.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_source","output"],"properties":{"keywords_csv":{"type":"string","description":"Raw CSV content (Ahrefs/SEMrush format). Either this or keywords array is required."},"keywords":{"type":"array","items":{"type":"object","required":["keyword","volume","kd"],"properties":{"keyword":{"type":"string"},"volume":{"type":"number"},"kd":{"type":"number"}}},"description":"Array of keywords with volume and KD. Either this or keywords_csv is required."},"config":{"type":"object","description":"Filter thresholds. Defaults are very permissive since customers typically pre-filter in Ahrefs.","properties":{"max_kd":{"type":"number","default":100,"description":"Max keyword difficulty (0-100). Set lower to filter."},"min_volume":{"type":"number","default":0,"description":"Min search volume. Set higher to filter."},"max_volume":{"type":"number","default":999999,"description":"Max search volume. Set lower to filter."},"overlap_threshold":{"type":"number","default":0.3},"serp_depth":{"type":"number","default":10},"location_code":{"type":"number","default":2840},"language_code":{"type":"string","default":"en"}}},"assignment":{"type":"object","description":"Controls how clusters are distributed across sites","properties":{"priority_sites":{"type":"array","description":"Sites that should receive a scoring boost during assignment","items":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Site domain to boost"},"boost":{"type":"number","default":2,"description":"Score multiplier (1-10). Higher means more likely to win clusters."}}}},"max_clusters_per_site":{"type":"number","description":"Max clusters any single site can receive per run (velocity cap). Unset means no limit."},"min_clusters_per_site":{"type":"number","description":"Minimum clusters each site should receive. Unassigned clusters are redistributed to sites below this floor using a 4-tier matching cascade (subcategory, category token, keyword overlap, round-robin). Unset means no floor."},"scarcity_strength":{"type":"number","default":1,"description":"Controls distribution spread. 0 = pure relevance (best-match site always wins), 1 = balanced (default), 2-3 = aggressive spread (empty sites get stronger boost)."}}},"site_source":{"type":"object","required":["airtable_base_id","airtable_table_name","columns"],"properties":{"airtable_base_id":{"type":"string"},"airtable_table_name":{"type":"string"},"columns":{"type":"object","required":["website","categories","subcategories"],"properties":{"website":{"type":"string"},"site_name":{"type":"string"},"categories":{"type":"string"},"subcategories":{"type":"string"}}}}},"output":{"type":"object","required":["airtable_base_id","airtable_table_name"],"properties":{"airtable_base_id":{"type":"string"},"airtable_table_name":{"type":"string"},"clear_before_write":{"type":"boolean","default":false}}}}}}}},"responses":{"201":{"description":"Job created","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"estimated_time_minutes":{"type":"number"},"estimated_cost":{"type":"number"}}}}}},"400":{"description":"Validation error"},"429":{"description":"Rate limit exceeded"}},"tags":["Research"]}}}}
```
## Get cluster bulk job status
> Poll for the status of a bulk SERP clustering job. Returns progress info and summary when complete.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/serp-cluster-bulk/{jobId}":{"get":{"summary":"Get cluster bulk job status","description":"Poll for the status of a bulk SERP clustering job. Returns progress info and summary when complete.","responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["pending","parsing","fetching_serps","clustering","reading_sites","assigning","writing_results","completed","failed"]},"progress":{"type":"object","nullable":true,"properties":{"current":{"type":"number"},"total":{"type":"number"}}},"message":{"type":"string","nullable":true},"summary":{"type":"object","nullable":true,"description":"Available when status is completed"},"error":{"type":"string","nullable":true}}}}}},"404":{"description":"Job not found"}},"tags":["Research"]}}}}
```
## Generate articles from approved clusters
> Reads rows from the Airtable output table, creates articles in Cuppa, and dispatches generation.\
> By default only rows with Status = Assigned AND the Approved checkbox = true are included.\
> Articles appear in the Cuppa UI under the correct site. Status is written back to Airtable.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Research","description":"Keyword and competitor research"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/research/serp-cluster-bulk/{jobId}/generate":{"post":{"summary":"Generate articles from approved clusters","description":"Reads rows from the Airtable output table, creates articles in Cuppa, and dispatches generation.\nBy default only rows with Status = Assigned AND the Approved checkbox = true are included.\nArticles appear in the Cuppa UI under the correct site. Status is written back to Airtable.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["settings"],"properties":{"filter":{"type":"object","properties":{"status":{"type":"string","default":"Assigned","description":"Must match clustering output single-select (usually Assigned)"},"require_approved_checkbox":{"type":"boolean","default":true,"description":"When true, require Approved checkbox. Set false for legacy Status-only tables."},"approved_checkbox_field":{"type":"string","default":"Approved"},"airtable_filter_formula":{"type":"string","description":"Full Airtable filterByFormula; overrides status and checkbox logic"},"sites":{"type":"array","items":{"type":"string"}},"max_articles":{"type":"number"}}},"settings":{"type":"object","required":["language","region"],"properties":{"language":{"type":"string"},"region":{"type":"string"},"model":{"type":"string"},"tone":{"type":"string"},"pov":{"type":"string"},"generate_images":{"type":"boolean","default":false},"include_introduction":{"type":"boolean","default":true},"include_conclusion":{"type":"boolean","default":true}}},"airtable_status_column":{"type":"string","description":"Column name in Airtable to write generation status updates"},"cuppa_article_id_field":{"type":"string","default":"Cuppa Article ID","description":"Airtable column for article UUID; must match filter and write-back"}}}}}},"responses":{"201":{"description":"Generation job created","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"articles_queued":{"type":"number"},"sites_involved":{"type":"number"}}}}}},"400":{"description":"Cluster job not complete or invalid request"},"404":{"description":"Cluster job not found"}},"tags":["Research"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://learn.cuppa.ai/rest-api/research.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.