Research

Keyword and competitor research

Research keyword opportunities

post

Get keyword ideas from seed keywords using DataForSEO. Returns search volume, difficulty, and intent data. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

seed_keywordsstring[] · min: 1 · max: 10Required

Seed keywords to research

locationstringOptionalDefault: United States

languagestringOptionalDefault: en

include_questionsbooleanOptionalDefault: true

limitnumber · min: 1 · max: 500OptionalDefault: 50

Responses

200

Keyword research results

application/json

totalnumberOptional

seed_keywordsstring[]Optional

locationstringOptional

post

/v1/research/keywords

HTTPcURLJavaScriptPython

POST /v1/research/keywords HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 105

{
  "seed_keywords": [
    "text"
  ],
  "location": "United States",
  "language": "en",
  "include_questions": true,
  "limit": 50
}

200

Keyword research results

{
  "keywords": [
    {
      "keyword": "text",
      "search_volume": 1,
      "keyword_difficulty": 1,
      "cpc": 1,
      "competition": "text",
      "search_intent": "text",
      "is_question": true
    }
  ],
  "total": 1,
  "seed_keywords": [
    "text"
  ],
  "location": "text"
}

Analyze SERP for a keyword

post

Get detailed SERP analysis including organic results, SERP features, People Also Ask, and search intent. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

keywordstring · max: 200Required

locationstringOptionalDefault: United States

languagestringOptionalDefault: en

Responses

200

SERP analysis results

application/json

keywordstringOptional

locationstringOptional

search_intentstring · enumOptionalPossible values:

difficultystring · enumOptionalPossible values:

serp_featuresstring[]Optional

people_also_askstring[]Optional

unique_domainsnumberOptional

post

/v1/research/serp

HTTPcURLJavaScriptPython

POST /v1/research/serp HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "keyword": "text",
  "location": "United States",
  "language": "en"
}

200

SERP analysis results

{
  "keyword": "text",
  "location": "text",
  "search_intent": "informational",
  "difficulty": "Low",
  "serp_features": [
    "text"
  ],
  "organic_results": [
    {
      "position": 1,
      "url": "text",
      "title": "text",
      "domain": "text"
    }
  ],
  "people_also_ask": [
    "text"
  ],
  "unique_domains": 1
}

Analyze competitor keywords

post

Get keywords that a competitor domain ranks for. Useful for competitive analysis and content gap identification. Requires Power plan or higher.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

domainstringRequired

Competitor domain to analyze (e.g., "competitor.com")

locationstringOptionalDefault: United States

limitnumber · min: 1 · max: 200OptionalDefault: 50

Responses

200

Competitor keyword analysis

application/json

domainstringOptional

totalnumberOptional

total_volumenumberOptional

post

/v1/research/competitors

HTTPcURLJavaScriptPython

POST /v1/research/competitors HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "domain": "text",
  "location": "United States",
  "limit": 50
}

200

Competitor keyword analysis

{
  "domain": "text",
  "keywords": [
    {
      "keyword": "text",
      "search_volume": 1,
      "keyword_difficulty": 1,
      "cpc": 1,
      "competition": "text"
    }
  ],
  "total": 1,
  "total_volume": 1,
  "competition_breakdown": {
    "ANY_ADDITIONAL_PROPERTY": 1
  }
}

Google Trends data

post

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.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

keywordsstring[] · min: 1 · max: 5Required

Keywords to check trends for (max 5)

locationstringOptional

Location name (e.g. "United States")

time_rangestring · enumOptional

Time range for trend data

Default: past_12_monthsPossible values:

typestring · enumOptional

Search type

Default: webPossible values:

Responses

200

Trend data with direction, related topics, and rising queries

application/json

post

/v1/research/trends

HTTPcURLJavaScriptPython

POST /v1/research/trends HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "keywords": [
    "text"
  ],
  "location": "text",
  "time_range": "past_12_months",
  "type": "web"
}

200

Trend data with direction, related topics, and rising queries

{
  "data": {
    "keywords": [
      "text"
    ],
    "location": "text",
    "timeRange": "text",
    "searchType": "text",
    "items": [
      {}
    ]
  }
}

Web search via Perplexity

post

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.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

querystring · min: 1 · max: 500Required

Search query for web research

focusstring · enumOptional

Focus area to refine the search context

Default: generalPossible values:

Responses

200

Structured research result with citations

application/json

post

/v1/research/web-search

HTTPcURLJavaScriptPython

POST /v1/research/web-search HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "query": "text",
  "focus": "general"
}

200

Structured research result with citations

{
  "data": {
    "query": "text",
    "focus": "text",
    "result": "text",
    "citations": [
      "text"
    ],
    "usage": {
      "promptTokens": 1,
      "completionTokens": 1
    }
  }
}

Cluster keywords by intent and topic

post

Group keywords by search intent (informational, commercial, transactional, navigational) and topic clusters. Useful for content planning and site architecture.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

keywordsstring[] · min: 1 · max: 500Required

methodstring · enumOptionalDefault: bothPossible values:

Responses

200

Keyword clustering results

application/json

total_keywordsnumberOptional

methodstringOptional

post

/v1/research/cluster

HTTPcURLJavaScriptPython

POST /v1/research/cluster HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "keywords": [
    "text"
  ],
  "method": "both"
}

200

Keyword clustering results

{
  "intent_clusters": {
    "informational": [
      "text"
    ],
    "commercial": [
      "text"
    ],
    "transactional": [
      "text"
    ],
    "navigational": [
      "text"
    ]
  },
  "topic_clusters": [
    {
      "name": "text",
      "keywords": [
        "text"
      ],
      "count": 1
    }
  ],
  "total_keywords": 1,
  "method": "text"
}

Bulk SERP clustering with site assignment

post

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.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Body

application/json

keywords_csvstringOptional

Raw CSV content (Ahrefs/SEMrush format). Either this or keywords array is required.

Responses

201

Job created

application/json

400

Validation error

429

Rate limit exceeded

post

/v1/research/serp-cluster-bulk

HTTPcURLJavaScriptPython

POST /v1/research/serp-cluster-bulk HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 605

{
  "keywords_csv": "text",
  "keywords": [
    {
      "keyword": "text",
      "volume": 1,
      "kd": 1
    }
  ],
  "config": {
    "max_kd": 100,
    "min_volume": 0,
    "max_volume": 999999,
    "overlap_threshold": 0.3,
    "serp_depth": 10,
    "location_code": 2840,
    "language_code": "en"
  },
  "assignment": {
    "priority_sites": [
      {
        "domain": "text",
        "boost": 2
      }
    ],
    "max_clusters_per_site": 1,
    "min_clusters_per_site": 1,
    "scarcity_strength": 1
  },
  "site_source": {
    "airtable_base_id": "text",
    "airtable_table_name": "text",
    "columns": {
      "website": "text",
      "site_name": "text",
      "categories": "text",
      "subcategories": "text"
    }
  },
  "output": {
    "airtable_base_id": "text",
    "airtable_table_name": "text",
    "clear_before_write": false
  }
}

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "text",
  "estimated_time_minutes": 1,
  "estimated_cost": 1
}

Get cluster bulk job status

get

Poll for the status of a bulk SERP clustering job. Returns progress info and summary when complete.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

jobIdstring · uuidRequired

Responses

200

Job status

application/json

job_idstringOptional

statusstring · enumOptionalPossible values:

messagestring · nullableOptional

summaryobject · nullableOptional

Available when status is completed

errorstring · nullableOptional

404

Job not found

get

/v1/research/serp-cluster-bulk/{jobId}

HTTPcURLJavaScriptPython

GET /v1/research/serp-cluster-bulk/{jobId} HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "job_id": "text",
  "status": "pending",
  "progress": {
    "current": 1,
    "total": 1
  },
  "message": "text",
  "summary": {},
  "error": "text"
}

Generate articles from approved clusters

post

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.

Authorizations

ApiKeyAuth

X-API-KEYstringRequired

Path parameters

jobIdstring · uuidRequired

Body

application/json

airtable_status_columnstringOptional

Column name in Airtable to write generation status updates

cuppa_article_id_fieldstringOptional

Airtable column for article UUID; must match filter and write-back

Default: Cuppa Article ID

Responses

201

Generation job created

application/json

400

Cluster job not complete or invalid request

404

Cluster job not found

post

/v1/research/serp-cluster-bulk/{jobId}/generate

HTTPcURLJavaScriptPython

POST /v1/research/serp-cluster-bulk/{jobId}/generate HTTP/1.1
Host: api.cuppa.ai
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 412

{
  "filter": {
    "status": "Assigned",
    "require_approved_checkbox": true,
    "approved_checkbox_field": "Approved",
    "airtable_filter_formula": "text",
    "sites": [
      "text"
    ],
    "max_articles": 1
  },
  "settings": {
    "language": "text",
    "region": "text",
    "model": "text",
    "tone": "text",
    "pov": "text",
    "generate_images": false,
    "include_introduction": true,
    "include_conclusion": true
  },
  "airtable_status_column": "text",
  "cuppa_article_id_field": "Cuppa Article ID"
}

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "text",
  "articles_queued": 1,
  "sites_involved": 1
}