Public API: Keyword Discovery - Keyword Insights Documentation

Discover new keyword opportunities from a seed keyword — including autocomplete suggestions, related searches, People Also Ask, and search volume metrics.

Full endpoint reference available on Swagger.

Quick Start

Create a keyword discovery order from a seed keyword:

import os
import requests

API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}

payload = {
    "seed_keyword": "content marketing strategies",
    "language": "en",
    "location": "United States",
}

response = requests.post(
    f"{BASE_URL}/api/keyword-discovery/order/",
    headers=HEADERS,
    json=payload,
)

data = response.json()
print(data)
# {"status": true, "payload": {"id": "339ca10b-...", "status": "created", ...}}

Endpoints

Method	Path	Description
POST	`/api/keyword-discovery/order/`	Create a keyword discovery order
GET	`/api/keyword-discovery/order/{order_id}/`	Get order details and processing status (polling)
DELETE	`/api/keyword-discovery/order/{order_id}/`	Delete an order (owner only)
GET	`/api/keyword-discovery/order/{order_id}/keywords`	Get discovered keywords (paginated, filterable)
GET	`/api/keyword-discovery/orders/`	List your orders (paginated)
GET	`/api/keyword-discovery/languages/`	List supported languages
GET	`/api/keyword-discovery/locations/`	List all supported locations
GET	`/api/keyword-discovery/locations/{search}/`	Search locations by name (top 10 fuzzy matches)

Parameters

Create Order — Required

Parameter	Type	Description
`seed_keyword`	string	The main keyword to discover related keywords for
`language`	string	ISO 639-1 language code (e.g. `en`). See `/api/keyword-discovery/languages/`
`location`	string	Location name (e.g. `United States`). See `/api/keyword-discovery/locations/`

Create Order — Optional

Parameter	Type	Description
`folder_id`	string	Dashboard folder ID to organize the order. Also pulls workspace/domain settings if the folder is linked to a domain

Polling Order Status

Orders are processed asynchronously. Poll the order endpoint until payload.status is done (or error). Each data source reports its own progress in payload.processing_status; keyword metrics (volume, CPC, competition) are attached once processing_status.enrich_status is done.

import time

def wait_for_order(order_id, poll_interval=10, max_wait=300):
    """Poll until the order finishes processing."""
    start = time.time()
    while time.time() - start < max_wait:
        response = requests.get(
            f"{BASE_URL}/api/keyword-discovery/order/{order_id}/",
            headers=HEADERS,
        )
        response.raise_for_status()
        payload = response.json()["payload"]

        status = payload["status"]
        processing = payload.get("processing_status") or {}
        print(f"status: {status}, enrichment: {processing.get('enrich_status')}")

        if status == "error":
            raise RuntimeError("Order failed to process")
        if status == "done" and processing.get("enrich_status") == "done":
            return payload

        time.sleep(poll_interval)

    raise TimeoutError(f"Order not ready after {max_wait}s")

The order detail response also includes n_keywords (total discovered so far), a short keywords preview, and seed_keyword_data (metrics for the seed keyword itself).

Status	Meaning
`created`	Order accepted, processing not started
`processing`	Keyword sources are being fetched
`done`	All sources fetched — check `processing_status.enrich_status` for metric enrichment
`error`	Processing failed (credits are refunded automatically)

Retrieving Keywords

Once the order is complete, retrieve discovered keywords with filtering and sorting:

order_id = "339ca10b-80c1-4248-b8d0-c11377c204c7"

response = requests.get(
    f"{BASE_URL}/api/keyword-discovery/order/{order_id}/keywords",
    headers=HEADERS,
    params={
        "page_size": 50,
        "page_number": 1,
        "sort_by": "volume",
        "sort_order": "desc",
    },
)

data = response.json()["payload"]
print(f"Total keywords: {data['total_list_length']}")

for kw in data["list"]:
    print(f"  {kw['keyword']} — vol: {kw['volume']}, source: {kw['source']}")

Keywords Query Parameters

Pagination & sorting:

Parameter	Type	Default	Description
`page_size`	integer	10	Results per page (max 10000)
`page_number`	integer	1	Page number
`sort_by`	string	`volume`	Sort field: `keyword`, `source`, `volume`, `cpc`, `competition`
`sort_order`	string	`desc`	`asc` or `desc`

Source filtering:

Parameter	Type	Description
`source`	string	Filter by single source
`sources`	string[]	Filter by multiple sources (pass as repeated query params)

Available sources: seed_keyword, google_autocomplete, google_related_searches, people_also_ask, quora, reddit, google_search_console, generated_keywords Keyword filtering:

Parameter	Type	Description
`keywords_included`	string[]	Only include keywords containing these terms
`keywords_excluded`	string[]	Exclude keywords containing these terms
`include_hidden`	boolean	Include hidden keywords (default `false`)

Metric filters:

Parameter	Type	Description
`volume_from` / `volume_to`	integer	Search volume range
`cpc_from` / `cpc_to`	float	CPC range
`competition_from` / `competition_to`	float	Competition value range
`competition_cat`	string	Competition category: `all`, `low`, `medium`, `high`
`ctr_from` / `ctr_to`	float	CTR range (GSC data)
`clicks_from` / `clicks_to`	integer	Clicks range (GSC data)
`position_from` / `position_to`	float	SERP position range (GSC data)
`impressions_from` / `impressions_to`	integer	Impressions range (GSC data)

Managing Orders

Listing Your Orders

response = requests.get(
    f"{BASE_URL}/api/keyword-discovery/orders/",
    headers=HEADERS,
    params={
        "sort_by": "created_date",
        "sort_order": "desc",
        "search_query": "marketing",  # optional: filter by seed keyword
        "page_size": 10,
    },
)

data = response.json()["payload"]
for order in data["list"]:
    print(f"{order['seed_keyword']} — {order['status']} ({order['n_keywords']} keywords)")

Parameter	Type	Default	Description
`sort_by`	string	—	`seed_keyword` or `created_date`
`sort_order`	string	`asc`	`asc` or `desc`
`search_query`	string	—	Filter orders by seed keyword
`page_size`	integer	10	Results per page
`page_number`	integer	1	Page number

Deleting an Order

Only the order owner can delete an order:

response = requests.delete(
    f"{BASE_URL}/api/keyword-discovery/order/{order_id}/",
    headers=HEADERS,
)
# {"status": true, "payload": {"status": "deleted"}, "error": null}

Languages & Locations

Look up valid values for the create-order language and location fields:

# All supported languages: [{"name": "English", "code": "en"}, ...]
languages = requests.get(
    f"{BASE_URL}/api/keyword-discovery/languages/", headers=HEADERS
).json()["payload"]

# Search locations by name (top 10 fuzzy matches)
locations = requests.get(
    f"{BASE_URL}/api/keyword-discovery/locations/united/", headers=HEADERS
).json()["payload"]
# [{"name": "United States", "code": "us"}, {"name": "United Kingdom", "code": "gb"}, ...]

The full /api/keyword-discovery/locations/ list is large — prefer the search variant when you know the location name.

Customizations

Filtering by Source

Narrow results to specific keyword sources:

# Only autocomplete and People Also Ask keywords
response = requests.get(
    f"{BASE_URL}/api/keyword-discovery/order/{order_id}/keywords",
    headers=HEADERS,
    params={
        "sources": ["google_autocomplete", "people_also_ask"],
        "sort_by": "volume",
        "sort_order": "desc",
    },
)

Filtering by Metrics

Find high-volume, low-competition keywords:

response = requests.get(
    f"{BASE_URL}/api/keyword-discovery/order/{order_id}/keywords",
    headers=HEADERS,
    params={
        "volume_from": 1000,
        "competition_cat": "low",
        "sort_by": "volume",
        "sort_order": "desc",
    },
)

Complete Example

Create a keyword discovery order, poll until it completes, retrieve the top keywords by volume, and clean up:

import os
import time
import requests

API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}


def create_discovery(seed_keyword, language="en", location="United States"):
    """Create a keyword discovery order."""
    response = requests.post(
        f"{BASE_URL}/api/keyword-discovery/order/",
        headers=HEADERS,
        json={
            "seed_keyword": seed_keyword,
            "language": language,
            "location": location,
        },
    )
    response.raise_for_status()
    return response.json()["payload"]


def wait_for_order(order_id, poll_interval=10, max_wait=300):
    """Poll the order endpoint until processing completes."""
    start = time.time()
    while time.time() - start < max_wait:
        response = requests.get(
            f"{BASE_URL}/api/keyword-discovery/order/{order_id}/",
            headers=HEADERS,
        )
        response.raise_for_status()
        payload = response.json()["payload"]
        processing = payload.get("processing_status") or {}

        if payload["status"] == "error":
            raise RuntimeError("Order failed to process")
        if payload["status"] == "done" and processing.get("enrich_status") == "done":
            return payload

        time.sleep(poll_interval)
    raise TimeoutError(f"Order not ready after {max_wait}s")


def get_keywords(order_id, page_size=50, min_volume=0):
    """Fetch discovered keywords with optional volume filter."""
    response = requests.get(
        f"{BASE_URL}/api/keyword-discovery/order/{order_id}/keywords",
        headers=HEADERS,
        params={
            "page_size": page_size,
            "page_number": 1,
            "sort_by": "volume",
            "sort_order": "desc",
            "volume_from": min_volume,
        },
    )
    response.raise_for_status()
    return response.json()["payload"]


# --- Run ---

result = create_discovery("project management software")
order_id = result["id"]
print(f"Order created: {order_id}")

order = wait_for_order(order_id)
print(f"Processing complete: {order['n_keywords']} keywords discovered")

data = get_keywords(order_id, page_size=20, min_volume=500)
print(f"\nTop {len(data['list'])} keywords (of {data['total_list_length']} total):\n")

for kw in data["list"]:
    print(f"  {kw['keyword']:50s} vol: {kw['volume']:>6}  source: {kw['source']}")

# Optional cleanup
requests.delete(f"{BASE_URL}/api/keyword-discovery/order/{order_id}/", headers=HEADERS)

​Quick Start

​Endpoints

​Parameters

​Create Order — Required

​Create Order — Optional

​Polling Order Status

​Retrieving Keywords

​Keywords Query Parameters

​Managing Orders

​Listing Your Orders

​Deleting an Order

​Languages & Locations

​Customizations

​Filtering by Source

​Filtering by Metrics

​Complete Example

Quick Start

Endpoints

Parameters

Create Order — Required

Create Order — Optional

Polling Order Status

Retrieving Keywords

Keywords Query Parameters

Managing Orders

Listing Your Orders

Deleting an Order

Languages & Locations

Customizations

Filtering by Source

Filtering by Metrics

Complete Example