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
  }
}

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: 557

{
  "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
  },
  "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
}