Topic Research API

Quickstart

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data '{
    "topic": "electric cars",
    "search_country": "en-US"
}'

To increase your API limits, please choose your plan right from our pricing page.

Introduction

The Topic Research API generates topic structures with keyword research data delivered in Excel format.

Endpoints

POST /topic-research

Create a topic research job.

Base URL: https://workflow.api.kwrds.ai

Request Headers

X-API-KEY: (Required) Your API key for authentication.
Content-Type: (Required) Must be application/json.

Request Body

topic: (Required) Main topic to research. Example: "figma", "vegan recipes".
search_country: (Optional) Country code for localization (e.g., en-US). Default: en-US.
max_children: (Optional) Number of subtopics to generate (1-50). Default: 10.
manual_pages: (Optional) Array of custom subtopics to include. Example: ["tesla model 3"]. Default: [].
traffic_rate: (Optional) Traffic capture rate for projections (0.0-1.0). Default: 0.10 (10%).
conversion_rate: (Optional) Conversion rate for signup estimates (0.0-1.0). Default: 0.04 (4%).

Example Request

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data '{
    "topic": "figma",
    "search_country": "en-US",
    "traffic_rate": 0.10,
    "conversion_rate": 0.04
}'

Response (202 - Job Created)

JSON

{
  "job_id": "60965750-9e39-4a6f-af50-20fa60603d81"
}

Use the job_id to check status via GET /topic-research/{jobId}.

Note on Caching: Jobs are cached based on the combination of topic, search_country, max_children, manual_pages, traffic_rate, and conversion_rate. Changing any of these parameters will trigger a new computation, even for the same topic.

Response (200 - Completed)

If results are already available, you'll receive the full response immediately:

JSON

{
  "job_id": "312682ede30b4f7467edd6d752ed562e67c512679338e13d3f446408396e9fe1",
  "status": "DONE",
  "topic": "figma",
  "search_country": "en-US",
  "max_children": 10,
  "traffic_rate": 0.10,
  "conversion_rate": 0.04,
  "created_at": 1762387187138,
  "updated_at": 1762387716945,
  "final_report_url": "https://...",
  "summary": [
    {
      "keyword": "figma",
      "search_volume": 823000,
      "potential_traffic": 82300,
      "estimated_conversions": 3292
    },
    {
      "keyword": "Figma Design",
      "search_volume": 135000,
      "potential_traffic": 13500,
      "estimated_conversions": 540
    },
    {
      "keyword": "Total",
      "search_volume": 1500000,
      "potential_traffic": 150000,
      "estimated_conversions": 6000
    }
  ],
  "keyword_results": [
    {
      "keyword": "figma",
      "url": "https://kwrds-workflows-api.s3.us-west-2.amazonaws.com/..."
    }
  ]
}

GET /topic-research/{jobId}

Check job status and retrieve results.

Example Request

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research/60965750-9e39-4a6f-af50-20fa60603d81' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE'

Response (Processing)

JSON

{
  "job_id": "60965750-9e39-4a6f-af50-20fa60603d81",
  "status": "PROCESSING",
  "topic": "electric cars",
  "search_country": "en-US",
  "max_children": 10,
  "traffic_rate": 0.10,
  "conversion_rate": 0.04,
  "created_at": 1762046547271,
  "final_report_url": null
}

Response (Completed)

JSON

{
  "job_id": "60965750-9e39-4a6f-af50-20fa60603d81",
  "status": "DONE",
  "topic": "electric cars",
  "search_country": "en-US",
  "max_children": 10,
  "traffic_rate": 0.10,
  "conversion_rate": 0.04,
  "created_at": 1762046547271,
  "updated_at": 1762046729184,
  "final_report_url": "https://...",
  "summary": [
    {
      "keyword": "electric cars",
      "search_volume": 450000,
      "potential_traffic": 45000,
      "estimated_conversions": 1800
    },
    {
      "keyword": "Tesla",
      "search_volume": 823000,
      "potential_traffic": 82300,
      "estimated_conversions": 3292
    },
    {
      "keyword": "Total",
      "search_volume": 2500000,
      "potential_traffic": 250000,
      "estimated_conversions": 10000
    }
  ],
  "keyword_results": [
    {
      "keyword": "electric cars",
      "url": "https://kwrds-workflows-api.s3.us-west-2.amazonaws.com/..."
    },
    {
      "keyword": "Tesla",
      "url": "https://kwrds-workflows-api.s3.us-west-2.amazonaws.com/..."
    }
  ]
}

Response Fields:

status: PROCESSING, DONE, or FAILED
topic: The topic that was researched
search_country: Country/locale code used for the search
max_children: Number of subtopics generated
traffic_rate: Traffic capture rate used for projections (0.0-1.0)
conversion_rate: Conversion rate used for signup estimates (0.0-1.0)
created_at: Timestamp when job was created (milliseconds)
updated_at: Timestamp when job was last updated (milliseconds)
final_report_url: Download URL for Excel report (available when DONE)
summary: Array of summary data with search volumes and projections per keyword (available when DONE)
keyword_results: Array of keyword data URLs (available when DONE)

Summary Field Structure:

The summary field provides an aggregated overview of all researched keywords with traffic projections:

keyword: Keyword/topic name
search_volume: Total monthly search volume across all related keywords
potential_traffic: Estimated traffic based on your traffic_rate setting (default 10%)
estimated_conversions: Estimated conversions based on your conversion_rate setting (default 4%)

The last row always contains "keyword": "Total" with aggregated metrics across all keywords.

GET /topic-research/jobs

List all jobs for your account.

Example Request

cURL

curl --location 'https://workflow.api.kwrds.ai/topic-research/jobs' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE'

Query Parameters

limit: (Optional) Max results to return. Default: 20.

Response

Returns an array of all your topic research jobs:

JSON

[
  {
    "job_id": "60965750-9e39-4a6f-af50-20fa60603d81",
    "status": "DONE",
    "topic": "electric cars",
    "search_country": "en-US",
    "max_children": 10,
    "traffic_rate": 0.10,
    "conversion_rate": 0.04,
    "created_at": 1762046547271,
    "updated_at": 1762046729184,
    "final_report_url": "https://..."
  },
  {
    "job_id": "abc123...",
    "status": "PROCESSING",
    "topic": "sustainable fashion",
    "search_country": "en-US",
    "max_children": 15,
    "traffic_rate": 0.15,
    "conversion_rate": 0.05,
    "created_at": 1762050000000,
    "final_report_url": null
  }
]

Complete Example

bash

#!/bin/bash

API_KEY="YOUR_API_KEY_GOES_HERE"
BASE_URL="https://workflow.api.kwrds.ai"

# Create job
RESPONSE=$(curl -s -X POST "$BASE_URL/topic-research" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "sustainable fashion",
    "search_country": "en-US"
  }')

JOB_ID=$(echo $RESPONSE | jq -r '.job_id')
echo "Job created: $JOB_ID"

# Poll for completion
while true; do
  STATUS_RESPONSE=$(curl -s "$BASE_URL/topic-research/$JOB_ID" \
    -H "X-API-Key: $API_KEY")

  STATUS=$(echo $STATUS_RESPONSE | jq -r '.status')

  if [ "$STATUS" = "DONE" ]; then
    REPORT_URL=$(echo $STATUS_RESPONSE | jq -r '.final_report_url')
    echo "Download: $REPORT_URL"
    break
  fi

  sleep 30
done

Error Responses

401 Unauthorized

JSON

{
  "error": "X-API-Key header required"
}

400 Bad Request

JSON

{
  "error": "topic is required"
}

404 Not Found

JSON

{
  "error": "Job not found"
}

429 Too Many Requests

JSON

{
  "error": "Monthly quota exceeded for topic research"
}

Support

For questions or support, contact hello@kwrds.ai.