# Payments & Credit cards
Source: https://docs.keywordinsights.ai/account-management/payments-and-credit-cards/README
# Add or change VAT number
Source: https://docs.keywordinsights.ai/account-management/payments-and-credit-cards/add-or-change-vat-number
If you want to add your VAT number to your invoices;
Click the user icon in your top right-hand corner, and select -> Billing settings -> Manage billing settings.
![]()
Click "Update information."
![]()
Under TAX ID. Select your country.
Add the VAT number.
Click "Save".
![]()
# Changing billing name or address
Source: https://docs.keywordinsights.ai/account-management/payments-and-credit-cards/changing-billing-name-or-address
If you want to change your billing name or address;
Click the user icon in your top right-hand corner, and select -> Billing settings -> Manage billing settings.
Update your address or name here and click Save.
![]()
# Changing credit card details
Source: https://docs.keywordinsights.ai/account-management/payments-and-credit-cards/changing-credit-card-details
If you want to change your credit card details;
Click the user icon in your top right-hand corner, and select -> Billing settings -> Manage billing settings.
Click the edit icon next to your default payment method.
![]()
Follow the instructions to add a new card.
# Downloading invoices
Source: https://docs.keywordinsights.ai/account-management/payments-and-credit-cards/downloading-invoices
### How to download an invoice?
There are multiple ways to download an invoice.
Click the user icon in your top right-hand corner, and select -> Invoices.
![]()
Click to download invoices.
![]()
Click the user icon on your top right-hand corner, select -> Billing settings -> Manage billing settings -> Download under "Invoice history."
![]()
![]()
![]()
Please note that using the second method is not recommended, as Stripe will expire invoices after a certain period. Always use the first method, as we will locally host your invoices, and they will never expire.
# How to add a backup payment method
Source: https://docs.keywordinsights.ai/account-management/payments-and-credit-cards/how-to-add-a-backup-payment-method
If you want to add a backup payment method;
Click the user icon in your top right-hand corner, and select -> Billing Settings -> Manage billing settings.
Click "Add payment method."
Follow the instructions to add a new card.
![]()
# Pricing
Source: https://docs.keywordinsights.ai/account-management/pricing/README
# Legacy Subscriptions
Source: https://docs.keywordinsights.ai/account-management/pricing/legacy-subscriptions
### What is a Legacy Customer?
A legacy customer is anyone who purchased a Keyword Insights subscription on or before February 12th, 2025. These customers maintain access to the pricing structure, features, and terms that were available at the time of their initial subscription.
### How Do I Know If I'm a Legacy Customer?
You can easily verify your legacy status by following these steps:
1. Log into your Keyword Insights account
2. Navigate to "Settings"
3. Select "Subscriptions" from the menu
4. Look for text that identifies you as a legacy customer
![]()
If you see a notification stating you're on a legacy plan, your subscription is grandfathered under the terms that were in place when you originally subscribed.
### What Happens If I Want to Upgrade to an Annual Subscription from My Legacy Monthly Subscription?
If you're currently on a legacy subscription and wish to upgrade to an annual plan:
You'll be moved to our latest plans with updated pricing and features. Please note that **legacy plans are no longer available,** so any changes will be permanent. If you cancel, you won't be able to return to this plan. Refunds are not available for any plan changes, so we recommend reviewing the new plans carefully before making a decision.
### What Happens If I Cancel My Legacy Subscription?
If you decide to cancel your legacy subscription:
You won't be able to return to this plan at a later date. Refunds are not available for any plan changes or cancellations. We recommend reviewing your needs and our current offerings carefully before canceling your legacy subscription.
### Will You Grandfather Me Forever?
For the past 5 years, we've grandfathered all of our customers to honor our commitment to those who joined us early in our journey. However, there may be unforeseen circumstances such as massive price hikes, technical debt/limitations, etc. that could require us to revisit legacy plans.
In these rare cases, we may decide to cease your grandfathered offer. Should this occur, we promise to:
1. Provide you with plenty of advance notice
2. Offer alternative solutions that aim to maintain value comparable to your legacy plan
3. Work with you to find the best path forward that meets your needs
We value our legacy customers and will make every effort to continue supporting you on your current terms for as long as reasonably possible.
# Subscription
Source: https://docs.keywordinsights.ai/account-management/pricing/subscription/README
We offer both subscription and "pay as you go" pricing options for flexibility. However, please note that our monthly subscriptions are significantly cheaper and have additional benefits.
### Subscription plans, when paid monthly
![]()
### Subscription plans, when paid annually
![]()
All annual subscriptions will get a 20% discount. You can upgrade anytime.
### Detailed feature breakdown
You can see a detailed feature comparison breakdown [here](https://www.keywordinsights.ai/pricing/).
# Universal Credits Explained
Source: https://docs.keywordinsights.ai/account-management/pricing/subscription/universal-credits-explained
## We offer a robust universal credits system that allows subscribers to access any feature within the app using their credits.
### **Monthly/Annual subscription**
With a subscription, you receive X credits each month, which can be used across any feature in the app. At the end of each billing cycle, unused credits will be reset, and a fresh set of credits will be added. If you cancel your subscription, all remaining credits will expire at the end of your billing period.
### Credit top-up (For users with a Subscription)
If you run out of credits before your quota is replenished, you can purchase additional credits as a top-up. These credits are available at discounted rates based on your subscription plan.
### **Pay as you go**
For occasional users, we offer a pay-as-you-go option with no commitment. Purchase unlimited credits anytime, valid for 30 days. These credits can be used **exclusively for keyword clustering**. If you need search intent data, it’s available for an additional 1 credit per keyword and for rank checking it costs an additional credit. So it means you need 3 credits per keyword to cluster, classify search intent and get rank data. This is perfect for users who prefer flexibility without a monthly subscription.
**Note:** Accessing features like content briefs or writer assistant requires a monthly subscription.
### How do you calculate credits for clustering?
The number of required credits depends on the insights you choose and the number of keywords you upload. 1 keyword = 1 credit.
If you enable search intent for your clustering, you have to pay one additional credit and one additional credit for rank checking
**E.g.1,** If you upload 40,000 keywords, you will need 40,000 credits to cluster them.
**E.g.2,** If you upload 40,000 keywords and select search intent alongside clustering, you will need 80,000 credits.
**E.g.2,** If you upload 40,000 keywords and select search intent alongside clustering and enable rank checking, you will need 120,000 credits.
Pro Tip: Even if you’re an occasional user, we recommend opting for the basic monthly subscription and topping up with additional clustering credits as needed. This approach gives you access to credits at a lower rate.
# Subscription Management
Source: https://docs.keywordinsights.ai/account-management/subscription-management/README
# Buying a subscription
Source: https://docs.keywordinsights.ai/account-management/subscription-management/buying-a-subscription
### How do I buy a monthly or annual subscription?
Go to **Settings -> Subscription -> Select the monthly or annual**
Select your subscription.
Save 20% with an Annual Subscription!
![]()
# Cancelling a subscription
Source: https://docs.keywordinsights.ai/account-management/subscription-management/cancelling-a-subscription
### How do I cancel a subscription?
It's straightforward to cancel a subscription. Go to Settings -> Subscription and click 'Cancel subscription."
You will be asked to confirm the cancellation and fill out a short survey; your subscription will be immediately cancelled once confirmed.
After your subscription is cancelled, your monthly clustering credits will be available until the end of your billing cycle. After the end of the billing cycle, these credits will be reset.
All of your credits including pay-as-you-go and any top-up credits will reset at the end of your billing period or on the effective cancellation date.
![]()
### How do i delete all my data and personal information?
You can download all your files and personal information by going to Account settings -> Manage personal data -> [Delete account.](https://app.keywordinsights.ai/settings/account)
![]()
![]()
### What happens after I cancel my subscription?
When you cancel your subscription, it remains active until the end of the current billing period.
During this time, you'll retain full access to all features. At the conclusion of the billing period, your subscription will officially end, and you will lose access to the subscription-only features.
All of your credits including pay-as-you-go and any top-up credits will reset at the end of your billing period or on the effective cancellation date.
### What happens to my data after I cancel my subscription?
You will have until the cancellation effective date to export and back up all your project data.
On that date, all project data will be **permanently deleted** and cannot be recovered.
### How do I cancel my \$1 trial?
Your \$1 trial will automatically expire after 7 days, and your account will revert to the free version. You won’t be charged or upgraded to any paid plan, and no action is needed on your part.
Please note that it's your sole responsibility to back up this data, as we cannot recover it or issue you a refund.
# Downgrading a subscription
Source: https://docs.keywordinsights.ai/account-management/subscription-management/downgrading-a-subscription
### How do I downgrade a subscription?
You can downgrade a subscription at any time.
Go to Settings -> Subscriptions -> Click the "Downgrade" button.
![]()
### How does it work?
For downgrades, we will move you to a lower subscription without any additional charges, and it takes effect at the end of the current billing period. i.e., suppose you're on the $299 (45K credits) plan and downgrade to the $145 package (15K credits). In that case, You will still be able to use your 45K credits until the end of your billing cycle; at the end of the billing cycle, we will reset your remaining/unused subscription clustering credits and charge you the new lower package of \$145.
# Pausing a subscription
Source: https://docs.keywordinsights.ai/account-management/subscription-management/pausing-a-subscription
### How do I pause a monthly subscription?
It's straightforward to pause a subscription.
A popup will be presented and you can choose between 1,2 or 3 months and pause your subscription.
![]()
### Can I use the tool while the subscription is paused?
Once you pause the subscription you’ll still have full access to all features until the end of your current billing cycle. After that, your subscription will be paused, and all features will be unavailable until you resume. For example, if you paused your subscription on May 27th but your renewal date is June 27th, the pause will only take effect on June 27th. (You won't be charged on the June 27th) This means you’ll still have full access to your subscription and credits up until that renewal date.
### Why should I pause my subscription?
Pausing your subscription lets you keep your data, settings, and account intact without being billed.
### How many times can i pause per year
Pause for **up to three months** and **only twice a year**.
### What happens at the end of the pause period?
Your plan will automatically resume on the scheduled unpause date, and you’ll be charged the full subscription amount immediately upon reactivation.
### Can i resume my subscription before the auto resume date?
Yes you can do this anytime. Go to Settings -> Subscription and click 'Resume subscription."
![]()
### What happens if i resume my subscription before the auto resume date?
When you resume your subscription manually before the auto resume, your account will be reactivated immediately, allowing you to use the application right away. However, since no payment was collected during the paused period, your credits will not be renewed until your next billing cycle. This means full access is restored instantly, but credit renewal will align with your upcoming scheduled payment.
### What happens to my subscription and PAYG credits during pause?
PAYG and Top-up credits will remain frozen until the subscription is renewed. Once the subscription is reactivated and the user is successfully charged, the associated subscription credits will be added to the account. Plus the PAYG and Top-up credits unfrozen and available immediately.
### Can I pause my annual subscription?
Unfortunately no.
# Subscription Renewal & Payment Policy
Source: https://docs.keywordinsights.ai/account-management/subscription-management/subscription-renewal-and-payment-policy
This guide explains how Keyword Insights handles annual subscription renewals, payment attempts, failed charges, data deletion, and refund policy.
### 1. Automatic Renewal
All Keyword Insights subscriptions are set to auto-renew by default.
* Your annual plan will automatically renew on your renewal date (visible in your billing settings).
* The plan and price will match your existing subscription unless you’ve made changes.
* The charge will be made using your default payment method on file.
Important: Please ensure your card is active and has sufficient funds before your renewal date to avoid service disruption.
### 2. Payment Attempt Schedule
If the initial payment fails, our payment processor (Stripe) will retry the charge:
* Up to 8 attempts
* Spread over a 21-day period
Each attempt will use the same card on file. You can update your payment method at any time from your account settings.
### 3. Failed Payment Notifications
If a payment attempt fails, we’ll notify you via email:
* First email: Immediately after the first failed attempt
* Second email: 7 days after the first failure
* Third email: 15 days after the first failure
These reminders are designed to give you enough time to update your payment method and ensure continuity of service.
### 4. Cancellation & Data Deletion
If we’re unable to successfully charge your card within the 21-day retry window:
* Your subscription will be automatically cancelled on the 21st day
* All of your associated data (projects, keywords, reports, etc.) will be permanently deleted
Please note: Once your data is deleted, we cannot recover it. This action is **final**.
### 5. Refund Policy
We operate with a strict **no refund** policy.
* All payments are final.
* Once the charge is successfully processed, no refunds will be issued under any circumstances.
No Refunds. No Exceptions.
***
# Upgrading a subscription
Source: https://docs.keywordinsights.ai/account-management/subscription-management/upgrading-a-subscription
### How do I upgrade a subscription?
You can Upgrade your subscription anytime.
Go to Settings -> **Subscriptions** -> Click the "**Select plan**" button.
![]()
### How does it work?
We will charge you the difference between the current and new packages if you upgrade your subscription. In addition, we give credit for the difference. i.e., If you're on the $58 plan (6K credits) and upgraded to the $145 plan (15K credits), we'll charge you $87 (Price difference) and add 9K credits (credit difference), and we will move you to the new subscription so your next bill is on the $145 plan.
# Team Management
Source: https://docs.keywordinsights.ai/account-management/team-management/README
We understand the importance of Teamwork, and unlike other tools, we don't want to tie you into expensive team plans. Even our basic plan comes with 3 user seats.
### How to invite a team member?
Go to Settings -> Organisation settings ->
Under "Add team members"
Add your teammates' email addresses and click "Send invite"
Your teammate will receive an email and click the Authenticate button to gain access to your organisation.
![]()
### Can a team member access my billing details?
The answer is no. Your team members can use your credits and cannot upgrade/downgrade or access billing details. Only the admin can access these features.
### How do I remove a team member?
Click the "Delete" icon to remove a member.
![]()
# Adding a Team Member
Source: https://docs.keywordinsights.ai/account-management/team-management/adding-a-team-member
We understand the importance of teamwork, and our system is built so its easier to invite, share and manage your team members.
### How do I invite a team member?
Click the user icon in your top right-hand corner, and select -> Team settings.
![]()
This is your team's control panel.
You can invite new users to your account from the Add team members section.
There are 2 ways to invite team members.
1. Adding your team member's email.
2. Sending an invite link to your team member.
Input your team members' email and click the 'Member' drop-down menu. Select the privilege and click "Send invite."
There are 3 types of privileges.
![]()
1. Member - A regular team member who can access their own projects and any shared/allowed projects.
2. Manager - A manager can manage team members and has full access to team reports, team projects and project-sharing settings.
3. Administrator - An administrator can access everything and share and manage managers and team members.
### How can I add additional team members?
Depending on your subscription, you will have an allocation of user seats.
| Basic | Professional | Premium |
| ----------- | ------------ | ------------ |
| 1 user seat | 3 user seat | 5 user seats |
You can add additional team members by buying a seat at \$10 /mo.
Click the user icon in your top right-hand corner, and select -> Team settings.
Click "**Add seats**"
Select the number of seats.
Click "**Buy**"
![]()
# Sharing Projects
Source: https://docs.keywordinsights.ai/account-management/team-management/sharing-projects
You can share projects and searches with your team members and collaborate effectively.
### How do I share a project?
Go to Projects, click 'Team' from the second tab.
![]()
Navigate to any project and select the project you want to share. Click the toggle under the Team Access column.
You can also share all of the projects in bulk by going to profile -> Team settings.
![]()
Under the Team section, toggle "**All members have access to team Projects**" This will instantly share all of your projects with your team members.
![]()
Please note the Team sharing feature is only available on the **professional or above plan**.
# Sharing Team Reports
Source: https://docs.keywordinsights.ai/account-management/team-management/sharing-team-reports
Need to manage a large team and track their collective usage? Our comprehensive team reports have got you covered!
### How do I use Team reports?
Go to projects, click 'Team', and now click 'Team reports.'
![]()
This report will show all the features used, who used it and how often.
![]()
Click filters to refine your search further.
![]()
Please note the Team reports feature is only available on the **premium plan**.
# User seats
Source: https://docs.keywordinsights.ai/account-management/team-management/user-seats
With our user seats feature you can invite you entire team and collaborate on your projects.
### How do i buy seats?
Go to Settings -> Click the + icon next to seats, select the number of seats and click buy.
![]()
### What is the cost for user seats?
Each seat costs \$10 per month.
So if you buy 2 seats, it will be an additional \$20 a month.
Tip: Upgrading to a higher plan with more seats can often be more cost-effective than purchasing additional seats individually. Visit our pricing comparison [page](https://www.keywordinsights.ai/pricing/) for full details.
# API Key Authentication
Source: https://docs.keywordinsights.ai/api/api-key-authentication
Create and use API keys to authenticate with the Keyword Insights API
API keys provide a simple, long-lived way to authenticate with the Keyword Insights public API. Unlike Bearer tokens (which expire), API keys remain valid until you delete them — making them ideal for scripts, integrations, and automated workflows.
API key access is available on **Professional** and **Premium** plans. If you're on a different plan, you'll be prompted to upgrade when attempting to create an API key.
### Creating an API Key
1. Log in to your [Keyword Insights dashboard](https://app.keywordinsights.ai).
2. Navigate to **API Keys** from the left sidebar menu.
3. Click the **Create API key** button.
4. Enter a descriptive name for the key (e.g. "Python scripts", "N8N integration").
5. Click **Create**.
Once created, your API key will be displayed **once**. Copy it immediately and store it in a secure location — you will not be able to see the full key again.
Your key will look like this:
```
kwi_sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abc
```
After you close the modal, the key list will show only the prefix (e.g. `kwi_sk_aBcDe...`) along with the creation date and last used date.
### Using the API Key
Pass your API key in the `X-API-Key` header with every request:
```python Python theme={null}
import requests
API_KEY = "kwi_sk_your_api_key_here"
BASE_URL = "https://api.keywordinsights.ai"
response = requests.get(
f"{BASE_URL}/api/user/",
headers={"X-API-Key": API_KEY},
)
print(response.json())
```
```javascript JavaScript theme={null}
const API_KEY = "kwi_sk_your_api_key_here";
const BASE_URL = "https://api.keywordinsights.ai";
async function getUser() {
const response = await fetch(`${BASE_URL}/api/user/`, {
headers: { "X-API-Key": API_KEY },
});
const data = await response.json();
console.log(data);
}
getUser();
```
Treat your API key like a password. Do not commit it to version control or share it publicly. Use environment variables to store it securely.
### Storing the Key Securely
We recommend loading your API key from an environment variable:
```bash theme={null}
export KWI_API_KEY="kwi_sk_your_api_key_here"
```
Then in Python:
```python Python theme={null}
import os
API_KEY = os.environ["KWI_API_KEY"]
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
```
### Example: Create a Clustering Order
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
payload = {
"project_name": "My clustering project",
"keywords": [
"keyword clustering",
"keyword research",
"topical authority",
],
"search_volumes": [2300, 3210, 5500],
"language": "en",
"location": "United States",
"device": "desktop",
"clustering_method": "volume",
"grouping_accuracy": 4,
"hub_creation_method": "medium",
"insights": ["cluster", "rank", "context"],
"url": "https://example.com",
"folder_id": "",
}
response = requests.post(
f"{BASE_URL}/api/keywords-insights/order/",
headers={"X-API-Key": API_KEY},
json=payload,
)
order = response.json()
print(order)
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const payload = {
project_name: "My clustering project",
keywords: [
"keyword clustering",
"keyword research",
"topical authority",
],
search_volumes: [2300, 3210, 5500],
language: "en",
location: "United States",
device: "desktop",
clustering_method: "volume",
grouping_accuracy: 4,
hub_creation_method: "medium",
insights: ["cluster", "rank", "context"],
url: "https://example.com",
folder_id: "",
};
async function createOrder() {
const response = await fetch(`${BASE_URL}/api/keywords-insights/order/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
const order = await response.json();
console.log(order);
}
createOrder();
```
The response will contain an `order_id` that you'll use to retrieve results once the order is processed.
### Managing API Keys
You can manage your API keys from the dashboard at any time:
* **View keys** — see all active keys with their prefix, creation date, and last used date.
* **Delete keys** — revoke a key immediately. Any application using that key will lose access.
To delete a key, click the trash icon next to the key and confirm the deletion.
Deleting an API key is immediate and permanent. Make sure no active integrations depend on the key before deleting it.
### API Key vs. Bearer Token (Deprecated)
| | API Key (Recommended) | Bearer Token (Deprecated) |
| ----------------- | --------------------------------- | ----------------------------------- |
| **How to obtain** | Dashboard → API Keys | Login endpoint or browser dev tools |
| **Header** | `X-API-Key: kwi_sk_...` | `Authorization: Bearer eyJ...` |
| **Expires** | Never (until deleted) | After a set period |
| **Best for** | Scripts, integrations, automation | — |
**Bearer token authentication is deprecated.** If you are currently using Bearer tokens, we strongly recommend migrating to API keys. Bearer tokens will continue to work for now, but may be removed in a future update.
### Migrating from Bearer Tokens
If you have existing code using Bearer tokens, switching to API keys is a one-line change — replace the `Authorization` header with `X-API-Key`:
```python Python theme={null}
# Before (deprecated)
headers = {"Authorization": f"Bearer {JWT_TOKEN}"}
# After (recommended)
headers = {"X-API-Key": API_KEY}
```
```javascript JavaScript theme={null}
// Before (deprecated)
const headers = { "Authorization": `Bearer ${JWT_TOKEN}` };
// After (recommended)
const headers = { "X-API-Key": API_KEY };
```
No other changes are needed — all API endpoints accept both authentication methods.
# API Use Cases
Source: https://docs.keywordinsights.ai/api/api-use-cases/README
This is the hub for all use cases for the Keyword Insights public API. Each page includes
basic request examples, supported parameters, customization options, and guidance on
retrieving results.
View the OpenAPI routes here: [https://api.keywordinsights.ai/apidocs/](https://api.keywordinsights.ai/apidocs/)
### Public API use cases
* [Clustering](/api/api-use-cases/public-api-clustering) — group keywords into topical clusters
* [Content Brief](/api/api-use-cases/public-api-content-brief) — generate structured briefs and outlines
* [Writer Agent](/api/api-use-cases/public-api-writer-agent) — generate long-form content drafts
* [Advanced Ranking](/api/api-use-cases/public-api-advanced-ranking) — run advanced SERP-based ranking analysis
* [Keyword Content](/api/api-use-cases/public-api-keyword-content) — build content based on keyword inputs
When using the public API, create an API key and include it with every request.
See [API Key Authentication](/api/api-key-authentication) to get started.
# N8N integration
Source: https://docs.keywordinsights.ai/api/api-use-cases/n8n-integration
This guide uses **Bearer token** authentication, which is deprecated. For new N8N setups, you can skip the login step entirely by using an **API key** in the `X-API-Key` header instead. See [API Key Authentication](/api/api-key-authentication).
On this page, you'll find the guide on how to connect Keyword Insights API with N8N to run clustering.
### Step 1
#### Authentication
Use an HTTP Requst node, ensure the route is correct
\`[https://api.keywordinsights.ai//authentication/login/](https://api.keywordinsights.ai/authentication/login/)\`and the method is "POST".Finally, enable the body option, and enable JSON type, and pass the following by replacing the values of your account email/password.
```
{
"email": "",
"password": ""
}
```
![]()
### Step 2
#### Creating a clustering order
Ensure the output of the Auth node shows in the second node.
![]()
Update the following settings:
* Method -> POST
* URL -> [https://api.keywordinsights.ai/api/keywords-insights/order/](https://api.keywordinsights.ai/api/keywords-insights/order/)
* Send Headers -> Enabled
* Header Parameter Key -> Authorization
* Header Paramater Value -> Bearer `{'{ $json.result.access_token }'}`
* Send Body -> Enabled
* JSON, Using JSON
![]()
Paste the following json into the body, make sure to update the keywords, volumes you want to cluster, and URL, you can also customize further based on the configuration you want. You can also pass `folder_id` if you want it placed in a specific folder in the platform.
```
{
"clustering_method": "volume",
"device": "desktop",
"grouping_accuracy": 4,
"hub_creation_method": "medium",
"insights": [
"cluster",
"rank",
"context"
],
"language": "en",
"location": "United States",
"project_name": "A Clustering project",
"keywords": [
"keyword clustering",
"keyword research",
"topical authority",
"clustering methods",
"page authority"
],
"search_volumes": [
2300,
3210,
5500,
2100,
1200
],
"url": "https://www.keywordinsights.ai/"
}
```
![]()
That's all!
# Public API: Advanced Ranking
Source: https://docs.keywordinsights.ai/api/api-use-cases/public-api-advanced-ranking
Analyze SERP rankings for your domain with top URLs, word counts, and related searches via the API
Analyze how a domain ranks for any keyword — get top SERP URLs, domain positions, word counts, and related searches.
Full endpoint reference available on [Swagger](https://api.keywordinsights.ai/apidocs/#/Keyword%20Ranking).
### Quick Start
Check how a domain ranks for a single keyword:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
payload = {
"keyword": "project management software",
"domain": "asana.com",
"language": "en",
"location": "United States",
}
response = requests.post(
f"{BASE_URL}/api/advanced-ranking/order/",
headers=HEADERS,
json=payload,
)
data = response.json()
print(data)
# {"status": true, "order_id": "2879fa0b-...", "cost": 1}
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
};
const payload = {
keyword: "project management software",
domain: "asana.com",
language: "en",
location: "United States",
};
async function createOrder() {
const response = await fetch(`${BASE_URL}/api/advanced-ranking/order/`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(data);
// {"status": true, "order_id": "2879fa0b-...", "cost": 1}
}
createOrder();
```
### Endpoints
| Method | Path | Description |
| ------ | -------------------------------------------------- | ------------------------------- |
| POST | `/api/advanced-ranking/order/` | Single keyword ranking analysis |
| GET | `/api/advanced-ranking/order/?order_id={id}` | Get single keyword results |
| POST | `/api/advanced-ranking/batch/order/` | Batch keyword ranking analysis |
| GET | `/api/advanced-ranking/batch/order/?order_id={id}` | Get batch results |
### Parameters
#### Single Keyword — Required
| Parameter | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------------------- |
| `keyword` | string | Target keyword to analyze |
| `domain` | string | Domain to track rankings for (e.g. `asana.com`) |
| `language` | string | Language code (e.g. `en`). See `/api/keywords-insights/languages/` |
| `location` | string | Location name (e.g. `United States`). See `/api/keywords-insights/locations/` |
#### Single Keyword — Optional
| Parameter | Type | Default | Description |
| -------------------- | ------- | --------- | ----------------------------------------------------------------------- |
| `device` | string | `desktop` | `desktop` or `mobile` |
| `include_word_count` | boolean | `false` | Include word count for top ranking pages. Costs 10 credits instead of 1 |
#### Batch — Required
| Parameter | Type | Description |
| ---------- | --------- | ---------------------------- |
| `keywords` | string\[] | Array of keywords to analyze |
| `domain` | string | Domain to track rankings for |
| `language` | string | Language code |
| `location` | string | Location name |
#### Batch — Optional
Same as single keyword: `device`, `include_word_count`.
### Cost
| Mode | Without word count | With word count |
| -------------- | -------------------- | ---------------------- |
| Single keyword | 1 credit | 10 credits |
| Batch | 1 credit per keyword | 10 credits per keyword |
### Customizations
#### Including Word Count
Enable `include_word_count` to get word counts for the top 10 ranking URLs. Useful for benchmarking content length:
```python Python theme={null}
payload = {
"keyword": "best CRM software",
"domain": "hubspot.com",
"language": "en",
"location": "United States",
"include_word_count": True, # 10 credits instead of 1
}
```
```javascript JavaScript theme={null}
const payload = {
keyword: "best CRM software",
domain: "hubspot.com",
language: "en",
location: "United States",
include_word_count: true, // 10 credits instead of 1
};
```
#### Batch Ranking
Analyze multiple keywords at once:
```python Python theme={null}
payload = {
"keywords": [
"project management software",
"best project management tools",
"project management for teams",
],
"domain": "asana.com",
"language": "en",
"location": "United States",
}
response = requests.post(
f"{BASE_URL}/api/advanced-ranking/batch/order/",
headers=HEADERS,
json=payload,
)
data = response.json()
print(f"Batch order: {data['order_id']} (cost: {data['cost']} credits)")
```
```javascript JavaScript theme={null}
const payload = {
keywords: [
"project management software",
"best project management tools",
"project management for teams",
],
domain: "asana.com",
language: "en",
location: "United States",
};
async function createBatchOrder() {
const response = await fetch(`${BASE_URL}/api/advanced-ranking/batch/order/`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(`Batch order: ${data.order_id} (cost: ${data.cost} credits)`);
}
createBatchOrder();
```
### Retrieving Results
Poll until the order status is `"done"`:
```python Python theme={null}
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}
order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717"
while True:
response = requests.get(
f"{BASE_URL}/api/advanced-ranking/order/",
headers=HEADERS,
params={"order_id": order_id},
)
data = response.json()["result"]["payload"]
if data["status"] == "done":
break
print("Processing...")
time.sleep(10)
results = data["results"]
print(f"Domain URLs in top 100: {results['n_domain_rankings']}")
for ranking in results["domain_rankings"]:
print(f" #{ranking['rank']} — {ranking['url']}")
print(f"\nTop 10 SERP results:")
for url_data in results["top_rankings"]:
wc = f" ({url_data['word_count']} words)" if url_data.get("word_count") else ""
print(f" {url_data['url']}{wc}")
print(f"\nRelated searches: {results['related_searches']}")
print(f"People Also Ask: {results['related_questions']}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = { "X-API-Key": API_KEY };
const order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717";
async function getResults() {
let data;
while (true) {
const url = new URL(`${BASE_URL}/api/advanced-ranking/order/`);
url.searchParams.append("order_id", order_id);
const response = await fetch(url, {
headers: HEADERS,
});
const json = await response.json();
data = json.result.payload;
if (data.status === "done") {
break;
}
console.log("Processing...");
await new Promise((r) => setTimeout(r, 10000));
}
const results = data.results;
console.log(`Domain URLs in top 100: ${results.n_domain_rankings}`);
for (const ranking of results.domain_rankings) {
console.log(` #${ranking.rank} — ${ranking.url}`);
}
console.log("\nTop 10 SERP results:");
for (const url_data of results.top_rankings) {
const wc = url_data.word_count ? ` (${url_data.word_count} words)` : "";
console.log(` ${url_data.url}${wc}`);
}
console.log(`\nRelated searches: ${results.related_searches}`);
console.log(`People Also Ask: ${results.related_questions}`);
}
getResults();
```
The results include:
| Field | Description |
| ------------------- | ------------------------------------------------------------------------- |
| `domain_rankings` | List of your domain's URLs that rank in the top 100, with their positions |
| `n_domain_rankings` | Total number of your domain's URLs in the top 100 |
| `top_rankings` | Top 10 SERP URLs (with optional word counts) |
| `related_searches` | Related searches from the SERP |
| `related_questions` | People Also Ask questions from the SERP |
### Complete Example
Analyze a domain's rankings for multiple keywords and summarize the results:
```python Python theme={null}
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_batch(keywords, domain, language="en", location="United States"):
"""Create a batch ranking order."""
response = requests.post(
f"{BASE_URL}/api/advanced-ranking/batch/order/",
headers=HEADERS,
json={
"keywords": keywords,
"domain": domain,
"language": language,
"location": location,
"include_word_count": True,
},
)
response.raise_for_status()
return response.json()
def wait_for_batch(order_id):
"""Poll until batch is complete."""
while True:
response = requests.get(
f"{BASE_URL}/api/advanced-ranking/batch/order/",
headers=HEADERS,
params={"order_id": order_id},
)
data = response.json()["result"]["payload"]
if data["status"] == "done":
return data["results"]
print("Processing...")
time.sleep(15)
# --- Run ---
keywords = [
"project management software",
"task management tool",
"team collaboration software",
]
result = create_batch(keywords, domain="asana.com")
order_id = result["order_id"]
print(f"Batch created: {order_id} (cost: {result['cost']} credits)")
results = wait_for_batch(order_id)
for item in results:
print(f"\n'{item['keyword']}': {item['n_domain_rankings']} URLs in top 100")
for r in item["domain_rankings"][:3]:
print(f" #{r['rank']} — {r['url']}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
};
async function createBatch(keywords, domain, language = "en", location = "United States") {
const response = await fetch(`${BASE_URL}/api/advanced-ranking/batch/order/`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify({
keywords,
domain,
language,
location,
include_word_count: true,
}),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
}
async function waitForBatch(order_id) {
while (true) {
const url = new URL(`${BASE_URL}/api/advanced-ranking/batch/order/`);
url.searchParams.append("order_id", order_id);
const response = await fetch(url, {
headers: HEADERS,
});
const json = await response.json();
const data = json.result.payload;
if (data.status === "done") {
return data.results;
}
console.log("Processing...");
await new Promise((r) => setTimeout(r, 15000));
}
}
// --- Run ---
async function run() {
const keywords = [
"project management software",
"task management tool",
"team collaboration software",
];
const result = await createBatch(keywords, "asana.com");
const order_id = result.order_id;
console.log(`Batch created: ${order_id} (cost: ${result.cost} credits)`);
const results = await waitForBatch(order_id);
for (const item of results) {
console.log(`\n'${item.keyword}': ${item.n_domain_rankings} URLs in top 100`);
for (const r of item.domain_rankings.slice(0, 3)) {
console.log(` #${r.rank} — ${r.url}`);
}
}
}
run();
```
# Public API: Clustering
Source: https://docs.keywordinsights.ai/api/api-use-cases/public-api-clustering
Create keyword clustering orders, check status, and retrieve results via the API
Cluster keywords by SERP similarity, detect search intent, and track rankings — all programmatically.
Full endpoint reference available on [Swagger](https://api.keywordinsights.ai/apidocs/#/Keyword%20Insights).
### Quick Start
Create a clustering order with the minimum required parameters:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
payload = {
"project_name": "My first cluster",
"keywords": ["keyword clustering", "keyword grouping", "cluster keywords"],
"search_volumes": [2300, 1200, 900],
"language": "en",
"location": "United States",
"insights": ["cluster", "context"],
"folder_id": "",
}
response = requests.post(
f"{BASE_URL}/api/keywords-insights/order/",
headers=HEADERS,
json=payload,
)
data = response.json()
print(data)
# {"status": true, "order_id": "2879fa0b-...", "cost": 150}
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
};
const payload = {
project_name: "My first cluster",
keywords: ["keyword clustering", "keyword grouping", "cluster keywords"],
search_volumes: [2300, 1200, 900],
language: "en",
location: "United States",
insights: ["cluster", "context"],
folder_id: "",
};
async function createOrder() {
const response = await fetch(`${BASE_URL}/api/keywords-insights/order/`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(data);
}
createOrder();
```
### Endpoints
| Method | Path | Description |
| ------ | -------------------------------------------------------------------- | ------------------------------- |
| POST | `/api/keywords-insights/order/` | Create a clustering order |
| GET | `/api/keywords-insights/order/?order_id={id}` | Check order status |
| GET | `/api/keywords-insights/order/json/{order_id}/` | Get results as JSON (paginated) |
| GET | `/api/keywords-insights/order/xlsx/{order_id}/` | Export results as XLSX |
| GET | `/api/keywords-insights/orders/?n_orders={n}` | List recent orders |
| GET | `/api/keywords-insights/order/cost/?n_keywords={n}&insights=cluster` | Estimate cost |
| GET | `/api/keywords-insights/languages/` | Supported languages |
| GET | `/api/keywords-insights/locations/` | Supported locations |
### Parameters
#### Required
| Parameter | Type | Description |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------ |
| `project_name` | string | Name shown in the dashboard |
| `keywords` | string\[] | List of keywords to cluster (min 5, max 200,000) |
| `search_volumes` | number\[] | Search volume per keyword (same length as `keywords`) |
| `language` | string | Language code (e.g. `en`). See `/api/keywords-insights/languages/` |
| `location` | string | Location name (e.g. `United States`). See `/api/keywords-insights/locations/` |
| `insights` | string\[] | Insight types: `cluster`, `context`, `rank` |
| `folder_id` | string | Dashboard folder ID to save the project into. Retrieve from the browser URL in the KWI dashboard |
#### Optional
| Parameter | Type | Default | Description |
| --------------------- | ------- | --------- | ----------------------------------------------------------------- |
| `clustering_method` | string | `volume` | `volume` or `agglomerative` |
| `grouping_accuracy` | integer | `4` | SERP overlap threshold (1–7). Higher = stricter clusters |
| `hub_creation_method` | string | `medium` | Topical cluster similarity: `soft`, `medium`, `hard` |
| `device` | string | `desktop` | SERP device: `desktop`, `mobile`, `tablet` |
| `mobile_type` | string | — | `iphone` or `android` (when `device` is `mobile`) |
| `tablet_type` | string | — | `ipad` or `android` (when `device` is `tablet`) |
| `url` | string | — | Domain URL for ranking. **Required** when `rank` is in `insights` |
### Insight Types
The `insights` array controls what analysis runs:
* **`cluster`** — Groups keywords by SERP similarity. **Required** for all clustering orders.
* **`context`** — Detects search intent (informational, commercial, transactional, navigational).
* **`rank`** — Tracks your domain's ranking for each keyword. Requires the `url` parameter.
**Full clustering order:**
```json theme={null}
"insights": ["cluster", "rank", "context"]
```
**Intent-only order** (no clustering, just intent classification):
```json theme={null}
"insights": ["context"]
```
### Customizations
#### Clustering Method
* **`volume`** (default) — Groups keywords based on shared SERP URLs. Controlled by `grouping_accuracy` (1 = loose, 7 = strict). Best for most use cases.
* **`agglomerative`** — Uses hierarchical clustering for larger keyword sets. Better for discovering broader topic relationships.
#### Topical Clusters
The `hub_creation_method` controls how tightly related keywords must be to form a topical cluster:
* **`soft`** — Broad grouping, more keywords per topical cluster
* **`medium`** — Balanced (recommended)
* **`hard`** — Strict grouping, fewer but more focused clusters
### Checking Order Status
Orders process asynchronously. Poll the status endpoint until `status` is `"done"`:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717"
response = requests.get(
f"{BASE_URL}/api/keywords-insights/order/",
headers=HEADERS,
params={"order_id": order_id},
)
data = response.json()
print(data["status"]) # "confirmed", "processing", or "done"
print(data["progress"]) # 0.0 to 1.0
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = { "X-API-Key": API_KEY };
const orderId = "2879fa0b-deae-4aab-ad87-fd8fb8db9717";
async function checkStatus() {
const url = new URL(`${BASE_URL}/api/keywords-insights/order/`);
url.searchParams.append("order_id", orderId);
const response = await fetch(url, { headers: HEADERS });
const data = await response.json();
console.log(data.status); // "confirmed", "processing", or "done"
console.log(data.progress); // 0.0 to 1.0
}
checkStatus();
```
When the order is complete, the response includes download links:
```json theme={null}
{
"status": "done",
"progress": 1.0,
"order_id": "2879fa0b-...",
"results_files": {
"xlsx": "https://api.keywordinsights.ai/api/keywords-insights/order/xlsx/2879fa0b-.../",
"google_sheets": "https://docs.google.com/spreadsheets/d/.../copy"
}
}
```
### Retrieving Results as JSON
Get paginated cluster data:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717"
response = requests.get(
f"{BASE_URL}/api/keywords-insights/order/json/{order_id}/",
headers=HEADERS,
params={
"page_size": 50,
"page_number": 1,
"sort_by": "search_volume",
"ascending": False,
},
)
data = response.json()
clusters = data["result"]["payload"]["clusters"]
for cluster in clusters:
print(f"{cluster['name']} — {cluster['number_of_keywords']} keywords, vol: {cluster['search_volume']}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = { "X-API-Key": API_KEY };
const orderId = "2879fa0b-deae-4aab-ad87-fd8fb8db9717";
async function getResults() {
const url = new URL(`${BASE_URL}/api/keywords-insights/order/json/${orderId}/`);
url.searchParams.append("page_size", "50");
url.searchParams.append("page_number", "1");
url.searchParams.append("sort_by", "search_volume");
url.searchParams.append("ascending", "false");
const response = await fetch(url, { headers: HEADERS });
const data = await response.json();
const clusters = data.result.payload.clusters;
clusters.forEach((cluster) => {
console.log(
`${cluster.name} — ${cluster.number_of_keywords} keywords, vol: ${cluster.search_volume}`
);
});
}
getResults();
```
**JSON results query parameters:**
| Parameter | Type | Default | Description |
| ------------- | ------- | --------------- | ---------------------------------------------------------- |
| `page_size` | integer | 50 | Results per page (max 1,000) |
| `page_number` | integer | 1 | Page number |
| `sort_by` | string | `search_volume` | Sort field (e.g. `search_volume`, `keyword`, `cluster_id`) |
| `ascending` | boolean | `false` | Sort direction |
| `filter_id` | string | — | Filter ID from the filters endpoint |
### Exporting as XLSX
Download results as an Excel file:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717"
response = requests.get(
f"{BASE_URL}/api/keywords-insights/order/xlsx/{order_id}/",
headers=HEADERS,
)
# Save the XLSX file
with open("clusters.xlsx", "wb") as f:
f.write(response.content)
```
```javascript JavaScript theme={null}
const fs = require("fs");
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = { "X-API-Key": API_KEY };
const orderId = "2879fa0b-deae-4aab-ad87-fd8fb8db9717";
async function downloadXlsx() {
const response = await fetch(`${BASE_URL}/api/keywords-insights/order/xlsx/${orderId}/`, {
headers: HEADERS,
});
const buffer = await response.arrayBuffer();
fs.writeFileSync("clusters.xlsx", Buffer.from(buffer));
}
downloadXlsx();
```
### Estimating Cost
Check how many credits an order will cost before creating it:
```python Python theme={null}
response = requests.get(
f"{BASE_URL}/api/keywords-insights/order/cost/",
headers=HEADERS,
params={"n_keywords": 500, "insights": ["cluster", "context"]},
)
print(response.json()) # {"cost": 1000}
```
```javascript JavaScript theme={null}
async function estimateCost() {
const url = new URL(`${BASE_URL}/api/keywords-insights/order/cost/`);
url.searchParams.append("n_keywords", "500");
url.searchParams.append("insights", "cluster");
url.searchParams.append("insights", "context");
const response = await fetch(url, { headers: HEADERS });
const data = await response.json();
console.log(data); // { cost: 1000 }
}
estimateCost();
```
**Cost per keyword by insight combination:**
| Insights | Cost per keyword |
| ------------------------------ | ---------------- |
| `cluster` only | 1 credit |
| `cluster` + `context` | 2 credits |
| `cluster` + `rank` | 2 credits |
| `cluster` + `context` + `rank` | 3 credits |
### Complete Example
End-to-end workflow: create an order, wait for completion, and download results.
```python Python theme={null}
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_order(keywords, volumes):
"""Create a clustering order."""
response = requests.post(
f"{BASE_URL}/api/keywords-insights/order/",
headers=HEADERS,
json={
"project_name": "API automation example",
"keywords": keywords,
"search_volumes": volumes,
"language": "en",
"location": "United States",
"insights": ["cluster", "context"],
"folder_id": "",
"clustering_method": "volume",
"grouping_accuracy": 4,
"hub_creation_method": "medium",
},
)
response.raise_for_status()
return response.json()
def wait_for_completion(order_id):
"""Poll until the order is done."""
while True:
response = requests.get(
f"{BASE_URL}/api/keywords-insights/order/",
headers=HEADERS,
params={"order_id": order_id},
)
data = response.json()
print(f"Status: {data['status']} ({data['progress']:.0%})")
if data["status"] == "done":
return data
time.sleep(30)
def get_results(order_id):
"""Fetch all clusters as JSON."""
response = requests.get(
f"{BASE_URL}/api/keywords-insights/order/json/{order_id}/",
headers=HEADERS,
params={"page_size": 100, "page_number": 1},
)
response.raise_for_status()
return response.json()
# --- Run ---
keywords = ["best running shoes", "running shoes review", "top sneakers for running"]
volumes = [12000, 8500, 3200]
result = create_order(keywords, volumes)
order_id = result["order_id"]
print(f"Order created: {order_id} (cost: {result['cost']} credits)")
wait_for_completion(order_id)
data = get_results(order_id)
for cluster in data["result"]["payload"]["clusters"]:
print(f" {cluster['name']} — {cluster['number_of_keywords']} kw, vol: {cluster['search_volume']}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = { "X-API-Key": API_KEY };
async function createOrder(keywords, volumes) {
const response = await fetch(`${BASE_URL}/api/keywords-insights/order/`, {
method: "POST",
headers: { ...HEADERS, "Content-Type": "application/json" },
body: JSON.stringify({
project_name: "API automation example",
keywords,
search_volumes: volumes,
language: "en",
location: "United States",
insights: ["cluster", "context"],
folder_id: "",
clustering_method: "volume",
grouping_accuracy: 4,
hub_creation_method: "medium",
}),
});
if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
return await response.json();
}
async function waitForCompletion(orderId) {
while (true) {
const url = new URL(`${BASE_URL}/api/keywords-insights/order/`);
url.searchParams.append("order_id", orderId);
const response = await fetch(url, { headers: HEADERS });
const data = await response.json();
console.log(`Status: ${data.status} (${(data.progress * 100).toFixed(0)}%)`);
if (data.status === "done") return data;
await new Promise((r) => setTimeout(r, 30000));
}
}
async function getResults(orderId) {
const url = new URL(`${BASE_URL}/api/keywords-insights/order/json/${orderId}/`);
url.searchParams.append("page_size", "100");
url.searchParams.append("page_number", "1");
const response = await fetch(url, { headers: HEADERS });
if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
return await response.json();
}
async function run() {
const keywords = ["best running shoes", "running shoes review", "top sneakers for running"];
const volumes = [12000, 8500, 3200];
const result = await createOrder(keywords, volumes);
const orderId = result.order_id;
console.log(`Order created: ${orderId} (cost: ${result.cost} credits)`);
await waitForCompletion(orderId);
const data = await getResults(orderId);
data.result.payload.clusters.forEach((cluster) => {
console.log(
` ${cluster.name} — ${cluster.number_of_keywords} kw, vol: ${cluster.search_volume}`
);
});
}
run();
```
# Public API: Content Brief
Source: https://docs.keywordinsights.ai/api/api-use-cases/public-api-content-brief
Generate AI-powered content briefs, retrieve SERP analysis, and create outlines via the API
Generate comprehensive content briefs with SERP-based headings, AI title/description suggestions, and word count benchmarks — all programmatically.
Full endpoint reference available on [Swagger](https://api.keywordinsights.ai/apidocs/#/Content%20Brief).
### Quick Start
Create a content brief for a target keyword:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
payload = {
"keyword": "content marketing strategies",
"language": "en",
"location": "United States",
"folder_id": "",
}
response = requests.post(
f"{BASE_URL}/api/content-brief/order/",
headers=HEADERS,
json=payload,
)
data = response.json()
print(data)
# {"status": true, "payload": {"id": "339ca10b-...", "status": true, "cost": 500}}
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const payload = {
keyword: "content marketing strategies",
language: "en",
location: "United States",
folder_id: "",
};
const response = await fetch(`${BASE_URL}/api/content-brief/order/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(data);
// {"status": true, "payload": {"id": "339ca10b-...", "status": true, "cost": 500}}
```
### Endpoints
| Method | Path | Description |
| ------ | -------------------------------------------------------------------------- | --------------------------- |
| POST | `/api/content-brief/order/` | Create a content brief |
| GET | `/api/content-brief/order/?id={id}` | Get brief results |
| DELETE | `/api/content-brief/order/?ids={id1}&ids={id2}` | Delete briefs |
| GET | `/api/content-brief/orders/?page=1&page_size=10` | List all briefs (paginated) |
| GET | `/api/content-brief/languages/` | Supported languages |
| POST | `/api/content-brief/order/{order_id}/outline/` | Generate AI outline |
| GET | `/api/content-brief/order/{order_id}/outline/?auto_generate_order_id={id}` | Get AI outline results |
### Parameters
#### Create Brief — Required
| Parameter | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------------------------------------ |
| `keyword` | string | Target keyword or topic |
| `language` | string | Language code (e.g. `en`). See `/api/content-brief/languages/` |
| `location` | string | Location name (e.g. `United States`). See `/api/keywords-insights/locations/` |
| `folder_id` | string | Dashboard folder ID to save the project into. Retrieve from the browser URL in the KWI dashboard |
### Retrieving Results
Content briefs process asynchronously. Poll the results endpoint until the data is ready:
```python Python theme={null}
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}
order_id = "339ca10b-80c1-4248-b8d0-c11377c204c7"
while True:
response = requests.get(
f"{BASE_URL}/api/content-brief/order/",
headers=HEADERS,
params={"id": order_id},
)
data = response.json()["result"]["payload"]
if data["status"]:
break
print("Processing...")
time.sleep(15)
# Brief is ready
print(f"Keyword: {data['keyword']}")
print(f"Avg word count: {data['word_count_avg']}")
print(f"Recommended: {data['word_count_min']}–{data['word_count_max']} words")
print(f"Pages analyzed: {data['pages_count']}")
print(f"Headings found: {data['headings_count']}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const order_id = "339ca10b-80c1-4248-b8d0-c11377c204c7";
let data;
while (true) {
const response = await fetch(`${BASE_URL}/api/content-brief/order/?id=${order_id}`, {
headers: { "X-API-Key": API_KEY },
});
const json = await response.json();
data = json.result.payload;
if (data.status) {
break;
}
console.log("Processing...");
await new Promise((r) => setTimeout(r, 15000));
}
// Brief is ready
console.log(`Keyword: ${data.keyword}`);
console.log(`Avg word count: ${data.word_count_avg}`);
console.log(`Recommended: ${data.word_count_min}–${data.word_count_max} words`);
console.log(`Pages analyzed: ${data.pages_count}`);
console.log(`Headings found: ${data.headings_count}`);
```
The results include:
| Field | Description |
| ----------------------------------- | ---------------------------------------------------------------------- |
| `raw` | SERP page structures with headings, bullet points, and content weights |
| `brief_title_suggests` | AI-generated meta title suggestions |
| `brief_description_suggests` | AI-generated meta description suggestions |
| `word_count_avg` | Average word count across top-ranking pages |
| `word_count_min` / `word_count_max` | Recommended word count range |
| `pages_count` | Number of SERP pages analyzed |
| `headings_count` | Total headings scraped from top results |
| `processing_status` | Status of each processing stage |
### Generating an AI Outline
After a content brief is complete, you can generate an AI-powered outline:
```python Python theme={null}
# Step 1: Trigger outline generation
response = requests.post(
f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
headers=HEADERS,
json={"additional_context": "Focus on B2B companies"}, # optional
)
auto_id = response.json()["result"]["payload"]["auto_generate_order_id"]
# Step 2: Poll until outline is ready
while True:
response = requests.get(
f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
headers=HEADERS,
params={"auto_generate_order_id": auto_id},
)
data = response.json()["result"]["payload"]
if data["status"]:
break
time.sleep(10)
print(data["string"]) # Full outline as text
```
```javascript JavaScript theme={null}
// Step 1: Trigger outline generation
const response = await fetch(`${BASE_URL}/api/content-brief/order/${order_id}/outline/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ additional_context: "Focus on B2B companies" }), // optional
});
const json = await response.json();
const auto_id = json.result.payload.auto_generate_order_id;
// Step 2: Poll until outline is ready
let data;
while (true) {
const response = await fetch(
`${BASE_URL}/api/content-brief/order/${order_id}/outline/?auto_generate_order_id=${auto_id}`,
{
headers: { "X-API-Key": API_KEY },
}
);
const json = await response.json();
data = json.result.payload;
if (data.status) {
break;
}
await new Promise((r) => setTimeout(r, 10000));
}
console.log(data.string); // Full outline as text
```
### Listing Briefs
Retrieve a paginated list of all your content briefs:
```python Python theme={null}
response = requests.get(
f"{BASE_URL}/api/content-brief/orders/",
headers=HEADERS,
params={"page": 1, "page_size": 20},
)
data = response.json()["result"]["payload"]
print(f"Total briefs: {data['total_orders']}")
for brief in data["orders"]:
print(f" {brief['keyword']} — {brief['status']}")
```
```javascript JavaScript theme={null}
const response = await fetch(`${BASE_URL}/api/content-brief/orders/?page=1&page_size=20`, {
headers: { "X-API-Key": API_KEY },
});
const json = await response.json();
const data = json.result.payload;
console.log(`Total briefs: ${data.total_orders}`);
for (const brief of data.orders) {
console.log(` ${brief.keyword} — ${brief.status}`);
}
```
### Complete Example
End-to-end: create a content brief, wait for results, then generate an AI outline.
```python Python theme={null}
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_brief(keyword, language="en", location="United States"):
"""Create a content brief order."""
response = requests.post(
f"{BASE_URL}/api/content-brief/order/",
headers=HEADERS,
json={"keyword": keyword, "language": language, "location": location, "folder_id": ""},
)
response.raise_for_status()
return response.json()["result"]["payload"]
def wait_for_brief(order_id):
"""Poll until the content brief is ready."""
while True:
response = requests.get(
f"{BASE_URL}/api/content-brief/order/",
headers=HEADERS,
params={"id": order_id},
)
data = response.json()["result"]["payload"]
if data["status"]:
return data
print("Brief processing...")
time.sleep(15)
def generate_outline(order_id, context=""):
"""Trigger AI outline generation and wait for results."""
response = requests.post(
f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
headers=HEADERS,
json={"additional_context": context},
)
auto_id = response.json()["result"]["payload"]["auto_generate_order_id"]
while True:
response = requests.get(
f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
headers=HEADERS,
params={"auto_generate_order_id": auto_id},
)
data = response.json()["result"]["payload"]
if data["status"]:
return data
time.sleep(10)
# --- Run ---
result = create_brief("best project management tools")
order_id = result["id"]
print(f"Brief created: {order_id} (cost: {result['cost']} credits)")
brief = wait_for_brief(order_id)
print(f"Target: {brief['word_count_min']}–{brief['word_count_max']} words")
print(f"Title suggestions: {brief['brief_title_suggests']}")
outline = generate_outline(order_id, context="Focus on remote teams")
print(f"\nAI Outline:\n{outline['string']}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
async function createBrief(keyword, language = "en", location = "United States") {
const response = await fetch(`${BASE_URL}/api/content-brief/order/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ keyword, language, location, folder_id: "" }),
});
const json = await response.json();
return json.result.payload;
}
async function waitForBrief(orderId) {
while (true) {
const response = await fetch(`${BASE_URL}/api/content-brief/order/?id=${orderId}`, {
headers: { "X-API-Key": API_KEY },
});
const json = await response.json();
const data = json.result.payload;
if (data.status) {
return data;
}
console.log("Brief processing...");
await new Promise((r) => setTimeout(r, 15000));
}
}
async function generateOutline(orderId, context = "") {
const response = await fetch(`${BASE_URL}/api/content-brief/order/${orderId}/outline/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ additional_context: context }),
});
const json = await response.json();
const autoId = json.result.payload.auto_generate_order_id;
while (true) {
const response = await fetch(
`${BASE_URL}/api/content-brief/order/${orderId}/outline/?auto_generate_order_id=${autoId}`,
{
headers: { "X-API-Key": API_KEY },
}
);
const json = await response.json();
const data = json.result.payload;
if (data.status) {
return data;
}
await new Promise((r) => setTimeout(r, 10000));
}
}
// --- Run ---
(async () => {
const result = await createBrief("best project management tools");
const orderId = result.id;
console.log(`Brief created: ${orderId} (cost: ${result.cost} credits)`);
const brief = await waitForBrief(orderId);
console.log(`Target: ${brief.word_count_min}–${brief.word_count_max} words`);
console.log(`Title suggestions: ${brief.brief_title_suggests}`);
const outline = await generateOutline(orderId, "Focus on remote teams");
console.log(`\nAI Outline:\n${outline.string}`);
})();
```
# Public API: Keyword Content
Source: https://docs.keywordinsights.ai/api/api-use-cases/public-api-keyword-content
Extract People Also Ask, Reddit/Quora questions, and AI-generated meta titles and descriptions via the API
Extract content research data for any keyword — People Also Ask questions, Reddit and Quora discussions, and AI-generated meta titles and descriptions.
Full endpoint reference available on [Swagger](https://api.keywordinsights.ai/apidocs/#/Keyword%20Content).
### Quick Start
Create a keyword content order to extract People Also Ask questions:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
payload = {
"keyword": "best project management tools",
"language": "en",
"location": "United States",
"content_insights": ["paa"],
}
response = requests.post(
f"{BASE_URL}/api/keyword-content/order/",
headers=HEADERS,
json=payload,
)
data = response.json()
print(data)
# {"status": true, "order_id": "2879fa0b-...", "cost": 50}
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
};
const payload = {
keyword: "best project management tools",
language: "en",
location: "United States",
content_insights: ["paa"],
};
async function createOrder() {
const response = await fetch(`${BASE_URL}/api/keyword-content/order/`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(data);
// {"status": true, "order_id": "2879fa0b-...", "cost": 50}
}
createOrder();
```
### Endpoints
| Method | Path | Description |
| ------ | ------------------------------------------- | ------------------------------ |
| POST | `/api/keyword-content/order/` | Create a keyword content order |
| GET | `/api/keyword-content/order/?order_id={id}` | Get order status and results |
### Parameters
#### Required
| Parameter | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------------- |
| `keyword` | string | Target keyword to research |
| `language` | string | Language code (e.g. `en`). See `/api/content-brief/languages/` |
| `location` | string | Location name (e.g. `United States`). See `/api/keywords-insights/locations/` |
| `content_insights` | string\[] | Types of content insights to extract (see below) |
#### Optional
| Parameter | Type | Default | Description |
| --------- | ------ | --------- | --------------------- |
| `device` | string | `desktop` | `desktop` or `mobile` |
### Content Insight Types
The `content_insights` array controls which data is extracted. You can combine multiple types in a single order:
| Insight | Description | Cost |
| ------------------- | ------------------------------------------ | ----------- |
| `paa` | People Also Ask questions from Google SERP | 50 credits |
| `reddit_questions` | Related Reddit discussions and questions | 50 credits |
| `quora_questions` | Related Quora questions | 50 credits |
| `meta_titles` | AI-generated meta title suggestions | 200 credits |
| `meta_descriptions` | AI-generated meta description suggestions | 200 credits |
Total cost = sum of selected insights.
### Customizations
#### All Content Insights
Extract everything in a single order:
```python Python theme={null}
payload = {
"keyword": "email marketing automation",
"language": "en",
"location": "United States",
"content_insights": [
"paa",
"reddit_questions",
"quora_questions",
"meta_titles",
"meta_descriptions",
],
}
# Cost: 50 + 50 + 50 + 200 + 200 = 550 credits
```
```javascript JavaScript theme={null}
const payload = {
keyword: "email marketing automation",
language: "en",
location: "United States",
content_insights: [
"paa",
"reddit_questions",
"quora_questions",
"meta_titles",
"meta_descriptions",
],
};
// Cost: 50 + 50 + 50 + 200 + 200 = 550 credits
```
#### Questions Only
Get user questions from multiple platforms at a lower cost:
```python Python theme={null}
payload = {
"keyword": "best CRM software",
"language": "en",
"location": "United States",
"content_insights": ["paa", "reddit_questions", "quora_questions"],
}
# Cost: 50 + 50 + 50 = 150 credits
```
```javascript JavaScript theme={null}
const payload = {
keyword: "best CRM software",
language: "en",
location: "United States",
content_insights: ["paa", "reddit_questions", "quora_questions"],
};
// Cost: 50 + 50 + 50 = 150 credits
```
### Retrieving Results
Poll until the order status is `"done"`:
```python Python theme={null}
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}
order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717"
while True:
response = requests.get(
f"{BASE_URL}/api/keyword-content/order/",
headers=HEADERS,
params={"order_id": order_id},
)
data = response.json()["result"]["payload"]
if data["status"] == "done":
break
print("Processing...")
time.sleep(10)
results = data["results"]
# People Also Ask
if "paa" in results:
print("People Also Ask:")
for q in results["paa"]:
print(f" - {q}")
# Reddit questions
if "reddit_questions" in results:
print("\nReddit questions:")
for q in results["reddit_questions"]:
print(f" - {q}")
# AI meta titles
if "meta_titles" in results:
print("\nSuggested meta titles:")
for title in results["meta_titles"]:
print(f" - {title}")
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = { "X-API-Key": API_KEY };
const order_id = "2879fa0b-deae-4aab-ad87-fd8fb8db9717";
async function getResults() {
let data;
while (true) {
const url = new URL(`${BASE_URL}/api/keyword-content/order/`);
url.searchParams.append("order_id", order_id);
const response = await fetch(url, {
headers: HEADERS,
});
const json = await response.json();
data = json.result.payload;
if (data.status === "done") {
break;
}
console.log("Processing...");
await new Promise((r) => setTimeout(r, 10000));
}
const results = data.results;
// People Also Ask
if (results.paa) {
console.log("People Also Ask:");
for (const q of results.paa) {
console.log(` - ${q}`);
}
}
// Reddit questions
if (results.reddit_questions) {
console.log("\nReddit questions:");
for (const q of results.reddit_questions) {
console.log(` - ${q}`);
}
}
// AI meta titles
if (results.meta_titles) {
console.log("\nSuggested meta titles:");
for (const title of results.meta_titles) {
console.log(` - ${title}`);
}
}
}
getResults();
```
The results include download links for CSV exports:
```python Python theme={null}
# Download CSV files
files = results.get("files", {}).get("csv", {})
for insight_type, download_url in files.items():
print(f"{insight_type}: {download_url}")
```
```javascript JavaScript theme={null}
// Download CSV files
const files = results.files?.csv || {};
for (const [insight_type, download_url] of Object.entries(files)) {
console.log(`${insight_type}: ${download_url}`);
}
```
### Complete Example
Extract People Also Ask and Reddit questions, then save results to a file:
```python Python theme={null}
import os
import time
import json
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
def create_content_order(keyword, insights, language="en", location="United States"):
"""Create a keyword content order."""
response = requests.post(
f"{BASE_URL}/api/keyword-content/order/",
headers=HEADERS,
json={
"keyword": keyword,
"language": language,
"location": location,
"content_insights": insights,
},
)
response.raise_for_status()
return response.json()
def wait_for_results(order_id):
"""Poll until results are ready."""
while True:
response = requests.get(
f"{BASE_URL}/api/keyword-content/order/",
headers=HEADERS,
params={"order_id": order_id},
)
data = response.json()["result"]["payload"]
if data["status"] == "done":
return data["results"]
print("Processing...")
time.sleep(10)
# --- Run ---
result = create_content_order(
keyword="best project management tools",
insights=["paa", "reddit_questions"],
)
order_id = result["order_id"]
print(f"Order created: {order_id} (cost: {result['cost']} credits)")
results = wait_for_results(order_id)
# Save to file
with open("content_research.json", "w") as f:
json.dump(results, f, indent=2)
paa_count = len(results.get("paa", []))
reddit_count = len(results.get("reddit_questions", []))
print(f"Saved {paa_count} PAA questions and {reddit_count} Reddit questions")
```
```javascript JavaScript theme={null}
const fs = require("fs");
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
};
async function createContentOrder(keyword, insights, language = "en", location = "United States") {
const response = await fetch(`${BASE_URL}/api/keyword-content/order/`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify({
keyword,
language,
location,
content_insights: insights,
}),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
}
async function waitForResults(order_id) {
while (true) {
const url = new URL(`${BASE_URL}/api/keyword-content/order/`);
url.searchParams.append("order_id", order_id);
const response = await fetch(url, {
headers: HEADERS,
});
const json = await response.json();
const data = json.result.payload;
if (data.status === "done") {
return data.results;
}
console.log("Processing...");
await new Promise((r) => setTimeout(r, 10000));
}
}
// --- Run ---
async function run() {
const result = await createContentOrder(
"best project management tools",
["paa", "reddit_questions"]
);
const order_id = result.order_id;
console.log(`Order created: ${order_id} (cost: ${result.cost} credits)`);
const results = await waitForResults(order_id);
// Save to file
fs.writeFileSync("content_research.json", JSON.stringify(results, null, 2));
const paa_count = (results.paa || []).length;
const reddit_count = (results.reddit_questions || []).length;
console.log(`Saved ${paa_count} PAA questions and ${reddit_count} Reddit questions`);
}
run();
```
# Public API: Keyword Discovery
Source: https://docs.keywordinsights.ai/api/api-use-cases/public-api-keyword-discovery
Generate keyword research from a seed keyword and retrieve enriched keyword data via the API
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](https://api.keywordinsights.ai/apidocs/#/Keyword%20Discovery).
### Quick Start
Create a keyword discovery order from a seed keyword:
```python theme={null}
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`.
```python theme={null}
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:
```python theme={null}
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
```python theme={null}
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:
```python theme={null}
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:
```python theme={null}
# 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:
```python theme={null}
# 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:
```python theme={null}
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:
```python theme={null}
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)
```
# Public API: Writer Agent
Source: https://docs.keywordinsights.ai/api/api-use-cases/public-api-writer-agent
Generate AI-powered articles with outlines, plans, and full content via the API
Generate full AI-written articles from a keyword — including research, outline, and polished content.
Full endpoint reference available on [Swagger](https://api.keywordinsights.ai/apidocs/#/Writer%20Agent).
### Quick Start
Create a writer agent order to generate an article:
```python Python theme={null}
import os
import requests
API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}
payload = {
"keyword": "content marketing strategies",
"language_code": "en",
"location_name": "United States",
"folder_id": "",
}
response = requests.post(
f"{BASE_URL}/api/writer-agent/order/",
headers=HEADERS,
json=payload,
)
data = response.json()
print(data)
# {"status": true, "payload": {"id": "550e8400-...", "keyword": "content marketing strategies", ...}}
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const payload = {
keyword: "content marketing strategies",
language_code: "en",
location_name: "United States",
folder_id: "",
};
const response = await fetch(`${BASE_URL}/api/writer-agent/order/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(data);
// {"status": true, "payload": {"id": "550e8400-...", "keyword": "content marketing strategies", ...}}
```
### Endpoints
| Method | Path | Description |
| ------ | ---------------------------------- | ------------------------------------------------- |
| POST | `/api/writer-agent/order/` | Create a writer agent order |
| GET | `/api/writer-agent/order/?id={id}` | Get order status and generated article |
| GET | `/api/writer-agent/options/` | Get available options (POV, content types, tones) |
### Parameters
#### Required
| Parameter | Type | Description |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `keyword` | string | The main keyword or topic for the article |
| `language_code` | string | ISO 639-1 language code (e.g. `en`) |
| `location_name` | string | Location name (e.g. `United States`). See `/api/keywords-insights/locations/` |
| `folder_id` | string | Dashboard folder ID to organize the order. Retrieve from the browser URL in the KWI dashboard |
#### Optional
| Parameter | Type | Default | Description |
| --------------------- | ------ | --------------------- | ----------------------------------------------------------------------------- |
| `point_of_view` | string | `First person (I/We)` | `First person (I/We)`, `Second Person (You)`, `Third Person (He/She/They/It)` |
| `content_type` | string | `article` | `article` or `landing_page` |
| `additional_insights` | string | — | Extra context or instructions for the AI (e.g. "Focus on B2B companies") |
### Customizations
#### Point of View
Control the writing perspective:
```python Python theme={null}
payload = {
"keyword": "best CRM software",
"language_code": "en",
"location_name": "United States",
"point_of_view": "Second Person (You)", # Speaks directly to the reader
}
```
```javascript JavaScript theme={null}
const payload = {
keyword: "best CRM software",
language_code: "en",
location_name: "United States",
point_of_view: "Second Person (You)", // Speaks directly to the reader
};
```
#### Content Type
Choose between article-style content or landing page copy:
```python Python theme={null}
payload = {
"keyword": "project management tool",
"language_code": "en",
"location_name": "United States",
"content_type": "landing_page",
}
```
```javascript JavaScript theme={null}
const payload = {
keyword: "project management tool",
language_code: "en",
location_name: "United States",
content_type: "landing_page",
};
```
#### Additional Context
Steer the AI with specific instructions:
```python Python theme={null}
payload = {
"keyword": "email marketing tips",
"language_code": "en",
"location_name": "United States",
"additional_insights": "Focus on e-commerce businesses. Include real-world case studies.",
}
```
```javascript JavaScript theme={null}
const payload = {
keyword: "email marketing tips",
language_code: "en",
location_name: "United States",
additional_insights: "Focus on e-commerce businesses. Include real-world case studies.",
};
```
### Getting Available Options
Retrieve all available options before creating an order:
```python Python theme={null}
response = requests.get(
f"{BASE_URL}/api/writer-agent/options/",
headers=HEADERS,
)
options = response.json()["result"]["payload"]
print("Points of view:", options["points_of_view"])
print("Content types:", options["content_types"])
print("Tones of voice:", [t["name"] for t in options["tones_of_voice"]])
```
```javascript JavaScript theme={null}
const response = await fetch(`${BASE_URL}/api/writer-agent/options/`, {
headers: { "X-API-Key": API_KEY },
});
const json = await response.json();
const options = json.result.payload;
console.log("Points of view:", options.points_of_view);
console.log("Content types:", options.content_types);
console.log("Tones of voice:", options.tones_of_voice.map((t) => t.name));
```
### Retrieving Results
Writer agent orders process through multiple stages (outline, plan, article). Poll until the article is generated:
```python Python theme={null}
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}
order_id = "550e8400-e29b-41d4-a716-446655440000"
while True:
response = requests.get(
f"{BASE_URL}/api/writer-agent/order/",
headers=HEADERS,
params={"id": order_id},
)
data = response.json()["result"]["payload"]
status = data.get("processing_status", {})
print(f"Status: {data.get('status', 'processing')}")
if data.get("generated_article"):
break
time.sleep(30)
print(data["generated_article"])
```
```javascript JavaScript theme={null}
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
const order_id = "550e8400-e29b-41d4-a716-446655440000";
let data;
while (true) {
const response = await fetch(`${BASE_URL}/api/writer-agent/order/?id=${order_id}`, {
headers: { "X-API-Key": API_KEY },
});
const json = await response.json();
data = json.result.payload;
console.log(`Status: ${data.status || "processing"}`);
if (data.generated_article) {
break;
}
await new Promise((r) => setTimeout(r, 30000));
}
console.log(data.generated_article);
```
### Complete Example
End-to-end: create a writer agent order, wait for the article, and save it.
```python Python theme={null}
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_article(keyword, language="en", location="United States", **kwargs):
"""Create a writer agent order."""
payload = {
"keyword": keyword,
"language_code": language,
"location_name": location,
"folder_id": "",
**kwargs,
}
response = requests.post(
f"{BASE_URL}/api/writer-agent/order/",
headers=HEADERS,
json=payload,
)
response.raise_for_status()
return response.json()["result"]["payload"]
def wait_for_article(order_id):
"""Poll until the article is generated."""
while True:
response = requests.get(
f"{BASE_URL}/api/writer-agent/order/",
headers=HEADERS,
params={"id": order_id},
)
data = response.json()["result"]["payload"]
if data.get("generated_article"):
return data
print(f"Processing... status: {data.get('status', 'unknown')}")
time.sleep(30)
# --- Run ---
result = create_article(
keyword="best project management tools for startups",
point_of_view="Second Person (You)",
content_type="article",
additional_insights="Include comparisons and pricing information",
)
order_id = result["id"]
print(f"Order created: {order_id}")
article = wait_for_article(order_id)
# Save the article
with open("article.md", "w") as f:
f.write(article["generated_article"])
print(f"Article saved ({len(article['generated_article'])} characters)")
```
```javascript JavaScript theme={null}
const fs = require("fs");
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";
async function createArticle(keyword, language = "en", location = "United States", options = {}) {
const payload = {
keyword,
language_code: language,
location_name: location,
folder_id: "",
...options,
};
const response = await fetch(`${BASE_URL}/api/writer-agent/order/`, {
method: "POST",
headers: {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
const json = await response.json();
return json.result.payload;
}
async function waitForArticle(orderId) {
while (true) {
const response = await fetch(`${BASE_URL}/api/writer-agent/order/?id=${orderId}`, {
headers: { "X-API-Key": API_KEY },
});
const json = await response.json();
const data = json.result.payload;
if (data.generated_article) {
return data;
}
console.log(`Processing... status: ${data.status || "unknown"}`);
await new Promise((r) => setTimeout(r, 30000));
}
}
// --- Run ---
(async () => {
const result = await createArticle("best project management tools for startups", "en", "United States", {
point_of_view: "Second Person (You)",
content_type: "article",
additional_insights: "Include comparisons and pricing information",
});
const orderId = result.id;
console.log(`Order created: ${orderId}`);
const article = await waitForArticle(orderId);
// Save the article
fs.writeFileSync("article.md", article.generated_article);
console.log(`Article saved (${article.generated_article.length} characters)`);
})();
```
# How to use the Public API?
Source: https://docs.keywordinsights.ai/api/how-to-use-the-public-api
Our public API is documented with Swagger and can be accessed at [https://api.keywordinsights.ai/apidocs](https://api.keywordinsights.ai/apidocs/).
**Bearer token authentication is deprecated.** We recommend switching to API keys, which are simpler to set up, don't expire, and don't require you to handle token refresh. See [API Key Authentication](/api/api-key-authentication) to get started. Bearer tokens will continue to work for now, but may be removed in a future update.
### Prerequisites to use the public API
You need to have a valid **Keyword Insights** subscription in order to use the public API.
Before using the public API, you must acquire a **Bearer token** for authentication so that our servers can verify who you are and that you have permission to use the API.
### How to use the interactive public API documentation
To use the Swagger UI interactively, you must first be authenticated.\
Follow the instructions below to generate a **Bearer token**.
Once you are authenticated, you can **Try it out** on any endpoint by providing your Bearer token and the required parameters.
### Authenticate and retrieve a Bearer token (email and password)
This approach is for users who signed up with an email and password (not via Google Sign In).\
If you signed up with **Create with Google**, use the Google Sign In approach in the next section instead:\
[How to authenticate with the public API and retrieve a bearer token? (Google Sign In Approach)](how-to-use-the-public-api.mdx#how-to-authenticate-with-the-public-api-and-retrieve-a-bearer-token-google-sign-in-approach)
1. Open the [API documentation](https://api.keywordinsights.ai/apidocs/), scroll to the bottom of the page, and locate the **Authentication** section.
![Authentication section in Keyword Insights Swagger public API]()
Alternatively, you can go directly to the authentication endpoint using this link:\
[Authentication → /authentication/login](https://api.keywordinsights.ai/apidocs/#/Authentication/post_authentication_login_)
You should now see the authentication request details, including a **Try it out** button.
![Click the Try it out button to get started using the Keyword Insights public API]()
2. After clicking **Try it out**, the request body field becomes editable.
1. Enter your valid email address and password, exactly as you would on `app.keywordinsights.ai`.
2. Click the large blue **Execute** button below the text field.
![Enter email and password, then click Execute]()
If your email and password are correct, you should see a **200** response code and a JSON response object containing a `result` object.
3. In the response, copy the value of the `access_token`.\
In the example below, the token starts with `eyJ0....` and ends with `...Mokg`. You will need this token in the next step.
![Viewing the access token upon a successful authentication request]()
4. In a text editor of your choice, paste the copied access token and prepend the word `Bearer` (with a capital **B**), separated by a single space.\
Your complete string should look similar to:
```
Bearer eyJ0e..rest_of_the_token...4AnRMokg
```
This full string (including the word `Bearer`) is what you will use as the **Authorization** header for any authenticated API request.\
Some endpoints also require additional arguments such as `order_id`, which you can usually find in the URL of the respective page in the application.
5. Validate your Bearer token using the steps in the section\
[Validate your Bearer Token](how-to-use-the-public-api.mdx#validate-your-bearer-token).
### Authenticate and retrieve a Bearer token (Google Sign In)
Use this approach if you signed up using **Create with Google** instead of creating a password during sign up.
If you signed up manually with an email and password, use the previous section instead:\
[How to authenticate with the public API and retrieve a bearer token? (Email and password approach)](how-to-use-the-public-api.mdx#how-to-authenticate-with-the-public-api-and-retrieve-a-bearer-token-email-and-password-approach)
1. In your browser of choice (Chrome in this example), open a new tab and open the **Network** tab in the developer tools.
![Opening the developer tools in Google Chrome]()
![Opening the Network tab in the Chrome developer tools]()
2. In the address bar, navigate to [https://app.keywordinsights.ai](https://app.keywordinsights.ai/).\
Before logging in, click the **clear** button in the Network tab so that you can easily see only the upcoming requests.
![Clearing the Network tab to more easily inspect the next requests]()
3. Click **LOG IN WITH GOOGLE** and follow the prompts in the pop-up window as you normally would when signing in to the application.
4. After you are logged in, go back to the Network tab and locate a successful request (for example, the `/user` request – but any authenticated request will work).
* Select the request.
* In the right-hand panel, make sure the **Headers** tab is selected.
* Scroll down until you find the **Authorization** header.
* Copy the entire value of the Authorization header, including the word `Bearer`.
![Copying the Bearer token from an authenticated request in the Network tab]()
5. Validate your Bearer token using the steps in\
[Validate your Bearer Token](how-to-use-the-public-api.mdx#validate-your-bearer-token).
### Validate your Bearer Token
To confirm that your **Bearer token** works correctly, you can call the **User** endpoint in Swagger.
1. In the Swagger UI, navigate to the **User** endpoint and click **Try it out** to make the input fields editable.
2. Paste the full Bearer token string (including the word `Bearer`) into the appropriate field.
3. Click the large blue **Execute** button.
![Entering the Bearer token to validate it via the User endpoint]()
![Executing the request to validate the Bearer token]()
4. If the Bearer token is valid, you should see a **200** response code and your user object in the response body.
![Successful response when validating the Bearer token]()
**Congratulations! You have successfully authenticated with our public API. You can now call any endpoint documented in the API reference.**
How much is the API and how is it calculated?
The API is available for **Professional** and **Premium** subscriptions.\
For clustering, we provide a calculation endpoint at\
[https://dev.api.keywordinsights.ai/apidocs](https://dev.api.keywordinsights.ai/apidocs/#/)\
that tells you how many credits are required based on your settings.\
The API itself has **no additional pricing** beyond your subscription and credit usage.
# N8N - Content Brief
Source: https://docs.keywordinsights.ai/api/n8n/n8n-content-brief
Create a basic N8N Flow for Content Briefs
## Step 1 - Authentication via API key
* Use an HTTP Request node and select the following options:
* Authentication: `Generic Credential Type`
* Generic Auth Type: `Header Auth`
* Header Auth: `Header Auth account`
![Authentication section in Mintlify]()
* Then click the `Edit Pencil icon` to open up the detail model to enter your API key:
* Then in the modal, add X-API-KEY: `kwi_sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abc`
![Authentication section in Mintlify]()
### Alternatively you can authenticate via username and password
* Use an HTTP Request node
* URL: `Keywordinsightsapi.keywordinsights.ai//authentication/login`
* Method: `POST`
* Body -> JSON: `{ "email": "", "password": ""}`
![Authentication section in Mintlify]()
## Step 2 - Creating a Content Brief Order
* Ensure the output of the Auth node shows in the second node
![Authentication section in Mintlify]()
* Paste the following json into the body,
* `folder_id`: optional if you want the project placed in a specific folder
* `secondary_keywords`: optional to provide more detail
* `keywords`: pass up to 25 keywords, in a comma separated list within the array brackets `[]`
```
{
"keywords": ["how to become a model"],
"language": "en",
"location": "United States",
"title_ai_order_id": "",
"title": "",
"folder_id": "",
"secondary_keywords": ""
}
```
![Body payload for Content Brief Orders]()
# N8N - Keyword Discovery
Source: https://docs.keywordinsights.ai/api/n8n/n8n-keyword-discovery
Create a basic N8N Flow for Keyword Discovery Orders
## Step 1 - Authentication via API key
* Use an HTTP Request node and select the following options:
* Authentication: `Generic Credential Type`
* Generic Auth Type: `Header Auth`
* Header Auth: `Header Auth account`
![Authentication section in Mintlify]()
* Then click the `Edit Pencil icon` to open up the detail model to enter your API key:
* Then in the modal, add X-API-KEY: `kwi_sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abc`
![Authentication section in Mintlify]()
### Alternatively you can authenticate via username and password
* Use an HTTP Request node
* URL: `Keywordinsightsapi.keywordinsights.ai/authentication/login`
* Method: `POST`
* Body -> JSON: `{ "email": "", "password": ""}`
![Authentication section in Mintlify]()
## Step 2 - Creating a Keyword Discovery Order
* Ensure the output of the Auth node shows in the second node if you are using the legacy username and sandbox
![Authentication section in Mintlify]()
* Paste the following json into the body,
* `folder_id`: optional if you want the project placed in a specific folder
```
{
"folder_id": "",
"language": "en",
"location": "United Kingdom",
"seed_keyword": "how to become a model in ukraine"
}
```
![Body payload for keyword discovery]()
# N8N Workflow - Content Brief
Source: https://docs.keywordinsights.ai/api/n8n/n8n-workflow-content-briefs
Entire Workflow for N8N Content Briefs
![N8N Workflow - Content Brief]()
```
{
"name": "Content Brief",
"nodes": [
{
"parameters": {},
"type": "n8n-nodes-base.manualTrigger",
"typeVersion": 1,
"position": [
128,
0
],
"id": "6f96c731-5a5f-4772-a9f8-5d59455913fe",
"name": "When clicking ‘Execute workflow’"
},
{
"parameters": {
"method": "POST",
"url": "https://api.keywordinsights.ai/authentication/login/",
"sendBody": true,
"specifyBody": "json",
"jsonBody": "{\n \"email\": \"premium@keywordinsights.ai\",\n \"password\": \"gl&Ai&dD3hrHK69sXrDe\"\n}",
"options": {}
},
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.3,
"position": [
416,
0
],
"id": "9aea1bcc-a31d-49f1-96c1-2abd12b75692",
"name": "Get JWT token"
},
{
"parameters": {
"method": "POST",
"url": "https://api.keywordinsights.ai/api/content-brief/order/",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "Authorization",
"value": "=Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTc2OTYxMjU3NiwianRpIjoiMDhlZDRjZDctMzkzNi00OTdhLTkyMjgtY2U3MTQ2OTA4ZWMxIiwidHlwZSI6ImFjY2VzcyIsInN1YiI6IjI2ODQ3ZDc1LTZiYjItNDAxZS1iZTk0LTA1NDczZGRmYmUyMiIsIm5iZiI6MTc2OTYxMjU3NiwiZXhwIjoxNzcyMjA0NTc2LCJhZG1pbl9hY2Nlc3MiOmZhbHNlLCJwdWJsaWNfYXBpX2FjY2VzcyI6dHJ1ZSwic2hlZXRzX2FkZG9uX2FwaV9hY2Nlc3MiOnRydWUsImlzX2d1ZXN0X3VzZXIiOmZhbHNlfQ.6-Fn0ZkbFb1G2wQlwmn3C14pTyNdVlplLp-ITtfs1ww"
},
{
"name": "Content-Type",
"value": "application/json"
}
]
},
"sendBody": true,
"contentType": "raw",
"rawContentType": "application/json",
"body": "{\"keyword\":\"best electric cars 2024\",\"language\":\"en\",\"location\":\"Canada\"}",
"options": {}
},
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.3,
"position": [
752,
0
],
"id": "7506ebff-2750-4238-ad83-42622f0cfa56",
"name": "HTTP Request1"
},
{
"parameters": {
"url": "https://api.keywordinsights.ai/api/content-brief/order/",
"sendQuery": true,
"specifyQuery": "json",
"jsonQuery": "={\"id\": \"{{ $('HTTP Request1').item.json.payload.id }}\"}",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "Authorization",
"value": "=Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTc2OTYxMjU3NiwianRpIjoiMDhlZDRjZDctMzkzNi00OTdhLTkyMjgtY2U3MTQ2OTA4ZWMxIiwidHlwZSI6ImFjY2VzcyIsInN1YiI6IjI2ODQ3ZDc1LTZiYjItNDAxZS1iZTk0LTA1NDczZGRmYmUyMiIsIm5iZiI6MTc2OTYxMjU3NiwiZXhwIjoxNzcyMjA0NTc2LCJhZG1pbl9hY2Nlc3MiOmZhbHNlLCJwdWJsaWNfYXBpX2FjY2VzcyI6dHJ1ZSwic2hlZXRzX2FkZG9uX2FwaV9hY2Nlc3MiOnRydWUsImlzX2d1ZXN0X3VzZXIiOmZhbHNlfQ.6-Fn0ZkbFb1G2wQlwmn3C14pTyNdVlplLp-ITtfs1ww"
}
]
},
"options": {}
},
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.3,
"position": [
1328,
0
],
"id": "7361c69f-4099-4066-947b-dc46da124b4e",
"name": "Pooling"
},
{
"parameters": {
"conditions": {
"options": {
"caseSensitive": true,
"leftValue": "",
"typeValidation": "strict",
"version": 3
},
"conditions": [
{
"id": "bed320d4-f909-4869-a332-b3fe91a44b8d",
"leftValue": "={{ $json.payload.status }}",
"rightValue": true,
"operator": {
"type": "boolean",
"operation": "notEquals"
}
}
],
"combinator": "and"
},
"options": {}
},
"type": "n8n-nodes-base.if",
"typeVersion": 2.3,
"position": [
1584,
0
],
"id": "e399b13d-5c12-42b4-9603-b74d8bcd4df5",
"name": "If"
},
{
"parameters": {},
"type": "n8n-nodes-base.noOp",
"typeVersion": 1,
"position": [
1904,
16
],
"id": "a09f8643-8f97-4e7a-99b6-75efeaa67bad",
"name": "No Operation, do nothing"
},
{
"parameters": {
"content": "## Pooling for results",
"height": 368,
"width": 736
},
"type": "n8n-nodes-base.stickyNote",
"typeVersion": 1,
"position": [
1024,
-176
],
"id": "72a2916b-7f9b-4135-b329-cfbc05bd88c3",
"name": "Sticky Note"
},
{
"parameters": {
"amount": 30
},
"type": "n8n-nodes-base.wait",
"typeVersion": 1.1,
"position": [
1104,
0
],
"id": "7553bbc8-f8fc-4451-8bdb-08faa6abe452",
"name": "Wait",
"webhookId": "5e9b3a86-86b2-492d-8f34-5b60165ad985"
},
{
"parameters": {
"content": "## Authentication\n\nEnsure to use your keyword insights email/password here, and you have public api access",
"height": 336
},
"type": "n8n-nodes-base.stickyNote",
"typeVersion": 1,
"position": [
352,
-160
],
"id": "86888612-415b-459d-8afc-61e3d1cf1533",
"name": "Sticky Note1"
},
{
"parameters": {
"content": "## Create order\nEnsure to customise order configuration here, like keyword, location and language. And folder id. Referr to API docs for more details",
"height": 368
},
"type": "n8n-nodes-base.stickyNote",
"typeVersion": 1,
"position": [
688,
-176
],
"id": "6ac8873f-5aac-4b6d-8187-1ec8ad88809d",
"name": "Sticky Note2"
}
],
"pinData": {},
"connections": {
"When clicking ‘Execute workflow’": {
"main": [
[
{
"node": "Get JWT token",
"type": "main",
"index": 0
}
]
]
},
"Get JWT token": {
"main": [
[
{
"node": "HTTP Request1",
"type": "main",
"index": 0
}
]
]
},
"HTTP Request1": {
"main": [
[
{
"node": "Wait",
"type": "main",
"index": 0
}
]
]
},
"Pooling": {
"main": [
[
{
"node": "If",
"type": "main",
"index": 0
}
]
]
},
"If": {
"main": [
[
{
"node": "Wait",
"type": "main",
"index": 0
}
],
[
{
"node": "No Operation, do nothing",
"type": "main",
"index": 0
}
]
]
},
"Wait": {
"main": [
[
{
"node": "Pooling",
"type": "main",
"index": 0
}
]
]
}
},
"active": false,
"settings": {
"executionOrder": "v1",
"availableInMCP": false
},
"versionId": "a4379261-4455-430b-bb04-f8a000744f56",
"meta": {
"templateCredsSetupCompleted": true,
"instanceId": "88ecfcf41c3d06aaa7328ad79aa95ab2c36706c0c1f7a49d83a2dd38d353d849"
},
"id": "QisT-dDgt4Rt5aJBF5xqL",
"tags": []
}
```
# N8N - Writer Assistant
Source: https://docs.keywordinsights.ai/api/n8n/n8n-writer-assistant
Create a basic N8N Flow for Writer Assistant Orders
## Step 1 - Authentication via API key
* Use an HTTP Request node and select the following options:
* Authentication: `Generic Credential Type`
* Generic Auth Type: `Header Auth`
* Header Auth: `Header Auth account`
![Authentication section in Mintlify]()
* Then click the `Edit Pencil icon` to open up the detail model to enter your API key:
* Then in the modal, add X-API-KEY: `kwi_sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abc`
![Authentication section in Mintlify]()
### Alternatively you can authenticate via username and password
* Use an HTTP Request node
* URL: `Keywordinsightsapi.keywordinsights.ai/authentication/login`
* Method: `POST`
* Body -> JSON: `{ "email": "", "password": ""}`
![Authentication section in Mintlify]()
## Step 2 - Creating a Writer Assistant Order
* Ensure the output of the Auth node shows in the second node if you are using the legacy username and sandbox
![Authentication section in Mintlify]()
* Paste the following json into the body,
* `folder_id`: optional if you want the project placed in a specific folder
* `secondary_keywords`: optional to provide more detail
* `workflow_type`: NEW | OPTIMIZE | CONTENT\_BRIEF
* `keywords`: pass up to 25 keywords, in a comma separated list within the array brackets `[]`
### Workflow Type: NEW
```
{
"folder_id": "",
"keyword": "how to become a model",
"language": "en",
"location": "United States",
"secondary_keywords": [],
"workflow_type": "NEW"
}
```
### Workflow Type: CONTENT\_BRIEF
* `content_brief_order_id`: equired parameter of an existing content brief from which you plan to create a Writer Assistant Order
```
{
"folder_id": "",
"workflow_type": "CONTENT_BRIEF",
"content_brief_order_id": "str"
}
```
### Workflow Type: OPTIMIZE
```
{
"folder_id": "",
"keyword": "news",
"language": "en",
"location": "United States",
"workflow_type": "OPTIMIZE",
"content_url": "https://www.bbc.com/...."
}
```
![Body payload for Writer Assistant Orders]()
# Data storage and limits
Source: https://docs.keywordinsights.ai/data-retention/data-storage-and-limits
### What happens to my data if I cancel my subscription?
If you cancel your subscription, we will delete your data at the end-of-billing date.
All of your data is **permanently deleted**, and we will never be able to recover the data for you.
Please make sure to export and back up your data before you cancel.
Tip: To avoid losing your data, consider pausing your subscription instead of canceling it. You can pause for up to 3 months, twice per year, during which we’ll securely store your data, settings, and other account details. You can unpause at any time to resume access.
### What happens to my Pay-as-you-go clustering projects?
Your Pay-as-you-go clustering projects will be automatically deleted after 30 days. Please make sure to export your projects within 30 days of running your order. We will send you several emails to remind you to export and back up your projects.
### How do I check the project deletion deadlines?
We will give you two warnings during your cancellation.
![]()
We will display a banner with the dates within the application.
![]()
You can also see the full details on your subscription page.
![]()
Please be advised that failure to act on your part, resulting in the deletion of your files, will render us unable to recover them. In accordance with our terms and conditions and GDPR compliance, we bear no liability for any data loss.
# Exporting Data
Source: https://docs.keywordinsights.ai/faqs/exporting-data
As clustering reports expanded from 10 to over 40 data columns, the previous export process occasionally hit Google Sheets row limits and struggled to handle larger reports, especially those containing pivot tables.
Many users also requested the ability to download raw CSV files for easier use in custom workflows, automations, and scripts.
The new export feature addresses all of these issues.
You can now export large datasets smoothly to either Google Sheets or CSV without limitations. The process is significantly faster, more stable, and designed to scale with your data needs.
Now you will see 2 simple export options.
**1. Export Full Project** – Export all project data, including pivot tables, with or without applied filters. You can choose to download it as a Google Sheet or Excel file.
![]()
**2. Export Raw Data (Non-Pivoted)** – Export all project data without pivot tables, with or without applied filters. Selecting this option enables the CSV export button, allowing you to download the complete dataset in raw CSV format directly from our servers.
![]()
# Frequently Asked Questions
Source: https://docs.keywordinsights.ai/faqs/frequently-asked-questions
How do I tell when my credits are added?
For monthly/yearly subscribers, new clustering credits will be added at the end of their billing cycle.
Click the User icon to see when the credits are refreshed.
![]()
What happens to my credits if I cancel my subscription?
After your subscription is cancelled, your monthly/annual credits will be available until the end At the end of your billing cycle, all credits including monthly, top-up, and pay-as-you-go credits will be reset and permanently deleted.
Do unused credits roll over every month?
No, credits do not roll-over. Any unused credits will be reset at the end of the billing cycle.
Can I try it before I buy it?
Yes, you can try our \$1 trial for 7 days. It comes with 600 universal credits.
What happens after my \$1 trial expires?
Your \$1 trial will expire in 7 days. After this, your credits will be reset and you will be restricted from using the tool. You will not be charged anything. (You can still buy credits via Pay as you go for using the clustering feature)
How do special characters in my language affect the output?
Special characters are common in many languages. Such as Norwegian, Thai, Swedish, German etc.
If you're using Microsoft Excel or Mac Numbers, Please make sure to export your files with UTF-8 encoding. Else your special characters will not be exported correctly, and Keyword insights will show you an error.
When possible, we highly recommend you upload an **excel XLXS** file when dealing with special characters instead CSVs. The CSV encoding can convert special characters into random unreadable text, and it will cause our clustering and hub/spoke algorithm to produce incorrect output results.
Some of my clusters appear really similar - why is this?
Please watch this video as it explains this in more detail. [https://snippet.wistia.com/medias/oaeqllw2a4](https://snippet.wistia.com/medias/oaeqllw2a4)
What languages does your keyword Context feature support?
We support up to 100+ languages.
What languages are supported by the Topic cluster feature?
Here is the list of supported languages.
* Afrikaans
* Albanian
* Arabic
* Aragonese
* Armenian
* Asturian
* Azerbaijani
* Bashkir
* Basque
* Bavarian
* Belarusian
* Bengali
* Bishnupriya Manipuri
* Bosnian
* Breton
* Bulgarian
* Burmese
* Catalan
* Cebuano
* Chechen
* Chinese (Simplified)
* Chinese (Traditional)
* Chuvash
* Croatian
* Czech
* Danish
* Dutch
* English
* Estonian
* Finnish
* French
* Galician
* Georgian
* German
* Greek
* Gujarati
* Haitian
* Hebrew
* Hindi
* Hungarian
* Icelandic
* Ido
* Indonesian
* Irish
* Italian
* Japanese
* Javanese
* Kannada
* Kazakh
* Kirghiz
* Korean
* Latin
* Latvian
* Lithuanian
* Lombard
* Low Saxon
* Luxembourgish
* Macedonian
* Malagasy
* Malay
* Malayalam
* Marathi
* Minangkabau
* Nepali
* Newar
* Norwegian (Bokmal)
* Norwegian (Nynorsk)
* Occitan
* Persian (Farsi)
* Piedmontese
* Polish
* Portuguese
* Punjabi
* Romanian
* Russian
* Scots
* Serbian
* Serbo-Croatian
* Sicilian
* Slovak
* Slovenian
* South Azerbaijani
* Spanish
* Sundanese
* Swahili
* Swedish
* Tagalog
* Tajik
* Tamil
* Tatar
* Telugu
* Turkish
* Ukrainian
* Urdu
* Uzbek
* Vietnamese
* Volapük
* Waray-Waray
* Welsh
* West Frisian
* Western Punjabi
* Yoruba
What's the Topic cluster?
What's the Hub/spoke model, and how is it different from clusters?
Once you have your keyword clusters, it may be helpful to know how closely related those clusters are to other clusters.
By grouping similar clusters together, we create Hubs and Spokes. Using these, you'll be able to produce what we call "hub articles" which link to "spoke articles".
In essence, our "hub and spoke" tab will make your content planning easier, allowing you to quickly identify and comprehensively cover a given content topic.
**Bonus tip**: Pull through the your keyword rankings and you'll be able to see internal linking opportunities, if you have relevant existing content.
In this example, "Hawaii vacation" will form the "Hub" content piece. This could be a category page or a long-form article.
Here we are show all the "clusters" in the Spoke column that are contextually related to the hub.
So, you can produce content around "Where to stay in Hawaii" or "Planning a honeymoon to Hawaii" and internally link to our main "Hawaii vacation" hub .
![]()
What countries does your keyword clustering feature support?
Keyword clustering is not language-specific but rather geo/country-specific. We support all the countries in the world.
Let's take a look at a few examples.
I have an SEO client in France, and I'm targeting users in France. When I prepare my keyword list, I will select all the keywords and search volume data for those keywords. I will choose ***France*** under the country dropdown when I run my order through Keyword Insights.
Keyword Insights will then scrape ***google.fr*** and build the clusters based on how keywords are ranking in google.fr.
You can choose to upload French keywords, English keywords, or any other language. Regardless of language, Keyword Insights will scrape google.fr for those keywords.
As you can see, the language has no influence whatsoever on our clustering process.
What languages are supported by the AI Writer assistant?
Here is the list of supported languages.
* English
* German
* Norwegian
* Swedish
* Danish
* Spanish
* French
* Dutch
* Ukranian
* Russian
* Hebrew
Do you have a public product roadmap?
We do not have a public roadmap. However, if you're a paying customer, you will get access to our private SEO Community. We often show our early previews and engage with our customers. You can also make feature requests. You can join the community by going [here](https://community.keywordinsights.ai/).
Do you have live chat support?
We provide live chat support for Professional and Premium subscribers. Basic subscribers get access to our email support with 24-48hr response time. Our operating hours are between 9 am - 5 pm GMT.
How is the opportunity score calculated?
Most tools see how much volume a keyword gets to create an opportunity score, but they don't take into account two important things:
1. A realistic number of visitors based on volume can be determined by looking at the [CTR study by AWR](https://www.advancedwebranking.com/ctrstudy/). Based on this study, if you rank in position 1, you can expect to get 38% of the clicks, position 2 gets 13%, position 3 gets 8% etc.
2. It doesn't consider where you currently rank (and, therefore, the opportunity).
So we calculate the opportunity score by doing the following.
If someone ranks in position 1 for a keyword, the opportunity score will be "0", as they already rank for it. However, if they rank in position 2, it will be the difference between the percentage scores of position 1 and position 2.
So we have 1 column, "maximum opportunity", which is position 1 (or 38%) multiplied by the search volume. Then another column called "current estimated traffic", which is whatever their current position is, multiplied by the volume. So if we were in position two, it would be 13% multiplied by the volume. The opportunity is then the difference between the two.
For example, "cats" has a search volume of 100. We rank in position 3.
Maximum opportunity = 38 (38% x 100) Current Estimated traffic = 8 (8% x 100) Opportunity = 30 (30 - 8).
![]()
My account is flagged as spam. How can I fix this?
Your account has been flagged as spam by Google. Google's system is quite sensitive and can occasionally generate false positives. We apologize for any inconvenience this may have caused. Please reach out to our support team through live chat or email, and we will promptly remove the block. Thank you for your understanding.
# Language Support
Source: https://docs.keywordinsights.ai/faqs/language-support
You can find details of language support for each feature here. We’re continually adding new languages, so if there’s one you’d like us to support, please contact our support team.
The following languages are supported across these features: **Keyword Clustering, SERP Similarity, SERP Analyzer, and Title AI.**
* Afrikaans
* Akan
* Albanian
* Amharic
* Arabic
* Armenian
* Azeri
* Balinese
* Basque
* Belarusian
* Bengali
* Bosnian
* Bulgarian
* Burmese
* Catalan
* Cebuano
* Chichewa
* Chinese (Simplified)
* Chinese (Traditional)
* Croatian
* Czech
* Danish
* Dutch
* English
* Español (Latinoamérica)
* Estonian
* Ewe
* Faroese
* Farsi
* Filipino
* Finnish
* French
* Frisian
* Ga
* Galician
* Ganda
* Georgian
* German
* Greek
* Gujarati
* Haitian
* Hausa
* Hebrew
* Hebrew (old)
* Hindi
* Hungarian
* Icelandic
* IciBemba
* Igbo
* Indonesian
* Irish
* Italian
* Japanese
* Kannada
* Kazakh
* Khmer
* Kinyarwanda
* Kirundi
* Kongo
* Korean
* Kreol Seselwa
* Kreol morisien
* Krio
* Kurdish
* Kyrgyz
* Lao
* Latvian
* Lingala
* Lithuanian
* Luo
* Macedonian
* Malagasy
* Malay
* Malayalam
* Maltese
* Maori
* Marathi
* Mongolian
* Montenegro
* Nepali
* Northern Sotho
* Norwegian
* Nyankole
* Oromo
* Pashto
* Pidgin
* Polish
* Portuguese
* Portuguese (Brazil)
* Portuguese (Portugal)
* Punjabi
* Quechua
* Romanian
* Romansh
* Russian
* Serbian
* Serbian (Latin)
* Sesotho
* Shona
* Silozi
* Sindhi
* Sinhalese
* Slovak
* Slovenian
* Somali
* Spanish
* Swahili
* Swedish
* Tajik
* Tamil
* Telugu
* Thai
* Tigrinya
* Tonga (Tonga Islands)
* Tshiluba
* Tswana
* Tumbuka
* Turkish
* Turkmen
* Ukrainian
* Urdu
* Uzbek
* Vietnamese
* Wolof
* Xhosa
* Yoruba
* Zulu
The following languages are supported across these features: **Keyword Discovery, Content briefs, Writer assistant, and AI Writer agent.**
* Polish
* Spanish
* Italian
* Norwegian
* German
* French
* Danish
* English
* Dutch
* Arabic
* Portuguese
# Affiliate Program
Source: https://docs.keywordinsights.ai/help-and-support/affiliate-program
Help others discover the power of Keyword Insights and get rewarded for it. When you refer someone to Keyword Insights using your unique referral link, you’ll earn 20% commission on every sale they make, for life.
This is more than a one-time payout. It’s a true passive income stream: every time someone you refer upgrades or renews, you get paid. No limits, no expiration.
Whether you’re recommending it to colleagues, clients, or your online audience, it’s a win-win. They get access to one of the most powerful topical authority platforms on the market and you get paid every step of the way.
### How do I join the affiliate program?
Signing up is quick and easy. Just head to our affiliate registration page and [create an account](https://www.keywordinsights.ai/affiliate-program/). Once you’re approved, you’ll get instant access to your unique referral link and dashboard.
From there, you can start promoting Keyword Insights and track your clicks, conversions, and commissions in real time.
If you’re already a user, you can log in with your existing account and activate your affiliate status from the dashboard.
![]()
### What platform do you use for your affiliate program?
We use [Tolt](https://app.tolt.io/) as our affiliate management program.
### How do i login to my dashboard?
Once approved, you can login to the dashboard by going [here](https://affiliates.keywordinsights.ai/login)
### **How to Use The Dashboard?**
Go to the login page, add your email address and click "Login"
![]()
You will get a code sent via email and you can use it to login to your dashboard.
![]()
### The Dashboard
![]()
You can view all your affiliate data in one place. Including referrals, commissions, payouts, and payment settings. From your dashboard, you’ll also be able to choose and manage your preferred payout method.
### What payout methods are available?
We support multiple payout options to suit your preference. You can choose to receive your commissions via Wise, PayPal, local bank transfer, or wire transfer. Simply select your preferred method in the payout settings of your affiliate dashboard.
### How to set my payout method?
Go to Settings -> Payment method -> Click "Update payment details"
![]()
Select your preferred payment method.
![]()
Click "Save"
### When will i get paid?
Payouts will happen automatically, 15 days after the end of each month, for the previous month.
### What is the payment threshold?
When your affiliate amount reaches \$100 you will be qualified to get a payout.
### What are the Terms & Conditions for using your affiliate program?
We’ve updated our Affiliate Terms & Conditions to better reflect how the program works. You can read the new terms [here](https://www.keywordinsights.ai/affiliate-program-terms-and-conditions/)
# Changelog
Source: https://docs.keywordinsights.ai/help-and-support/changelog
You can access our changelog here
# Getting Support
Source: https://docs.keywordinsights.ai/help-and-support/getting-support
### How does your support work?
Before starting a chat, we highly recommend reading through the documentation first. There's a good chance that your question has already been answered there. It could save you time and provide you with the information you need.
**Live chat support is available for all paying customers**. Our support is open between 9 am - 5 pm Monday and Friday. GMT+1 timezone.
If you're a non paying user you can send us an email at [support@keywordinsights.ai](mailto:support@keywordinsights.ai). We will respond to your messages within 48hours.
### How to contact support?
Log in to the app by going to [https://app.keywordinsights.ai/](https://app.keywordinsights.ai/)
Click 'Help Center'
![]()
Click 'Live chat.'
![]()
We aim to respond to all inquiries within a few hours, but it may take up to 24 hours during peak days. Your satisfaction is our priority, and we look forward to assisting you through live chat!
# What is Keyword Insights?
Source: https://docs.keywordinsights.ai/index
Keyword Insights helps you build topical authority so you can win visibility in Google and get mentioned in AI answers.
Instead of treating SEO as one great page at a time, Keyword Insights turns messy keyword research into a clear plan: topic clusters that show what pages to create, what gaps to fill, and what to prioritize to own a topic end to end.
From there, you can generate ranking focused content briefs based on what is already working in the SERPs, then create and optimise content with our AI Writer Agent tailored to the right page type and search intent.
It also goes beyond your website. Keyword Insights surfaces high intent Reddit, Quora, and YouTube conversations where your brand can contribute and earn credible mentions that influence what AI models say about you.
## Getting Started
Check out a video overview of our product.
**Note:** This comprehensive document guide is tailored for individuals seeking to deepen their understanding of Keyword Insights. Each lesson is thoughtfully crafted, presenting concise and informative videos that are systematically arranged for optimal comprehension. We strongly encourage all users to make the most of these invaluable resources.
# Anthropic Claude
Source: https://docs.keywordinsights.ai/integrations/claude-skill
Connect Keyword Insights to Claude to cluster keywords, classify intent, generate briefs, and write content through a simple conversation.
Keyword Insights has a native skill for Claude, Anthropic's AI assistant. Once set up, you can run your entire keyword research and content planning workflow by chatting with Claude. No manual exports, no switching between tools, no API calls to write yourself.
You can cluster a keyword list, classify search intent, generate content briefs, and trigger the Writer Agent, all from a single conversation.
![Clean Shot 2026 02 19 At 16 59 41@2x]()
API access requires a **Premium** plan. If you are on a lower plan, you will be prompted to upgrade when you try to create an API key.
## Prerequisites
Before you start, you will need:
1. A Keyword Insights account on the **Premium plan**
2. A KI API key (created from the API Keys section of your dashboard). Your key will start with `kwi_sk_`
3. Access to Claude with the Keyword Insights skill enabled
If you are using Claude via the API or in an agentic environment, set your API key as an environment variable:
```bash theme={null}
export KWI_API_KEY="kwi_sk_your_key_here"
```
***
## Where can I get the [Skill.MD](http://Skill.MD) file?
Download the [keyword-insights-SKILL.md](https://github.com/Suganthan-Mohanadasan/keywordinsights-skill)
## How to install the skill?
Once you download the **keyword-insights-SKILL.md** open Claude and go to \*\*Settings -> Capabilities \*\*
![Clean Shot 2026 02 19 At 18 27 35@2x]()
Click **+ Add** under skills
Select "**Upload a skill**"
![Clean Shot 2026 02 19 At 18 30 00@2x]()
Now upload the [**keyword-insights-SKILL.md**](http://keyword-insights-SKILL.md)\*\* **file**. \*\*
![Clean Shot 2026 02 19 At 18 31 15@2x]()
Now you have installed the skill.
Next step is to allow our API url to domain allowlist. (no https etc. Paste the url below as it is)
```bash theme={null}
api.keywordinsights.ai
```
![Clean Shot 2026 02 19 At 18 32 31@2x]()
That's all! Now you're ready!
## What You Can Ask Claude to Do?
Once connected, you can use plain English to trigger any of the following:
| What you say | What Claude does |
| -------------------------------------------------- | --------------------------------------------------------------- |
| "Cluster these keywords for the UK" | Submits a clustering order to KI and returns results |
| "What is the search intent for this list?" | Runs intent classification across your keyword set |
| "Generate a content brief for 'topical authority'" | Submits a content brief order and returns the structured brief |
| "Write a blog article about keyword clustering" | Triggers the Writer Agent (\~1,200 credits) |
| "How many credits do I have?" | Fetches your live balance from the KI API |
| "Build a topical map from this CSV" | Parses your file, clusters it, and summarises the hub structure |
***
## Step 1: Prepare Your Keywords
You can give Claude keywords in two ways.
**Upload a CSV file**
Export your keyword list from Ahrefs, Semrush, Google Search Console, or any other tool and upload the file directly in the Claude chat. Claude will automatically detect the keyword and search volume columns, handle different file encodings (including Ahrefs UTF-16 exports), and prepare the data for submission.
**Paste keywords directly**
If you have a short list, paste the keywords into the chat one per line. Include search volumes if you have them. If you do not, Claude will default to zero and the clustering will still work, though results will not be sorted by volume.
A minimum of 5 keywords is required per order.
***
## Step 2: Tell Claude What You Want
Use natural language. Claude will interpret your request and confirm the settings it plans to use before submitting the order.
Some examples:
```
"Cluster these keywords for the Australian market, desktop, grouping accuracy 5"
"Give me the search intent breakdown for this list"
"Generate a content brief for the keyword 'keyword clustering tool'"
"Cluster this CSV and save the results as a file I can download"
```
***
## Step 3: Confirm the Settings
Before submitting, Claude will confirm the parameters it is using. The defaults are sensible for most use cases:
| Setting | Default | Options |
| ----------------- | ---------------- | ----------------------------------------- |
| Language | English (`en`) | Any supported language code |
| Location | United States | Any country or region |
| Device | Desktop | Desktop, mobile, tablet |
| Grouping accuracy | 4 | 1 (broad) to 7 (strict) |
| Insights | Cluster + Intent | Cluster, intent, rank, or any combination |
If you want to change any of these, just mention it before or during the conversation. For example: "Use the UK, set grouping accuracy to 6, and I only want intent, not full clustering."
***
## Step 4: Wait for the Order to Process
Keyword Insights processes orders asynchronously using live SERP data. Claude will poll for results automatically and update you when they are ready.
Typical processing times:
| Order size | Estimated time |
| ------------------- | --------------- |
| Under 100 keywords | 1 to 3 minutes |
| 100 to 500 keywords | 3 to 10 minutes |
| 500+ keywords | 10+ minutes |
You do not need to do anything while the order is processing.
***
## Step 5: Work With Your Results
Once the order is complete, Claude will present a summary in the chat and offer to do more with the data.
For a clustering order, the summary will include:
* Total number of clusters created
* Top clusters by search volume
* Intent distribution across the full keyword set
You can then continue the conversation:
```
"Save the full results as a CSV"
"Show me all keywords in the top cluster"
"Which clusters should I prioritise for a new website?"
"Generate a content brief for the highest volume cluster"
```
***
## Credit Costs
| Operation | Approximate cost |
| --------------------------- | ------------------------- |
| Keyword clustering | 1 credit per keyword |
| Intent classification only | Less than full clustering |
| Content brief | \~100 credits |
| Writer Agent (full article) | \~1,200 credits |
Claude will always check your credit balance and warn you before submitting any order that costs a significant number of credits. It will not proceed without your confirmation on Writer Agent orders.
***
## Supported Inputs
Claude can parse keyword exports from:
* **Ahrefs** (tab-separated, UTF-16 encoded)
* **Semrush** (comma-separated, UTF-8)
* **Google Search Console** (via data export)
* **Moz, Mangools, SE Ranking, and most other tools** (standard CSV format)
* **Plain text** pasted directly into the chat
Column names are detected automatically. Claude looks for common variations like `Keyword`, `Search Query`, `Term`, `Volume`, `Search Volume`, and `Avg. monthly searches`.
***
## Tips
* Always specify the target location if you are not targeting the US. Claude defaults to United States.
* Use a higher grouping accuracy (5 or 6) for tighter, more specific clusters. Use a lower setting (2 or 3) if you want broader topic groups.
* For large keyword lists, ask Claude to summarise the top clusters first before diving into the full data.
* You can chain actions in a single session: cluster a list, identify the top hubs, and request briefs for the most important ones without starting a new conversation.
* If you want results saved as a file, just ask. Claude can output a CSV or XLSX and provide a download link.
***
## Troubleshooting
**Claude says my API key is invalid**
Double-check that your `KWI_API_KEY` environment variable is set correctly and that the key starts with `kwi_sk_`. Keys are created from the API Keys section of your KI dashboard.
**The order is taking a long time**
Large orders (500+ keywords) can take 10 minutes or more. Claude will continue polling and notify you when results arrive. Do not close the conversation. We don't recommend running large orders using Claude and only use it for smaller orders. For large orders use our API or UI.
**I got a credit error**
Your balance was insufficient to complete the order. Claude will show your current balance and the cost of the operation. Top up from the Billing section of your KI dashboard and resubmit.
**My CSV did not parse correctly**
Check that your file has a header row and that the keyword column is labelled in a standard way. If Claude cannot detect the columns automatically, paste a few example rows into the chat and tell it which column is the keyword and which is the volume.
***
## Related Pages
* [API Key Authentication](/api/api-key-authentication)
* [How to use the Public API?](/api/how-to-use-the-public-api)
* [Keyword Insights Tool Workflow](/learning-center/keyword-insights-tool-workflow)
# Google Search Console
Source: https://docs.keywordinsights.ai/integrations/google-search-console
Integrating Google Search Console with Keyword Insights provides a powerful way to improve your keyword analysis and optimize content strategy. By quickly downloading all your search keywords into the platform, you gain access to the full dataset that reveals valuable insights about search performance. Once integrated, you can cluster keywords to identify content gaps, areas where your content isn’t covering high-potential topics and spot content cannibalization, where multiple pages compete for the same keywords, potentially undermining search rankings.
### How to use the Google search console integration?
There are two ways to integrate Google search console with Keyword insights.
1. Under integrations page.
2. From the Keyword discovery page.
### Connecting Google search console pages from the integrations page
Go to Settings -> Integrations ([https://app.keywordinsights.ai/settings/integrations](https://app.keywordinsights.ai/settings/integrations))
![]()
Click 'Link account'.
![]()
Follow the Google prompts to connect your Google account.
![]()
Click 'Continue'
![]()
Click 'Contine' again.
The account will be added now.
### Connecting to Google search console from Keyword Discovery page
Go to Keyword discovery
Select Google search console option.
![]()
Follow the prompts by adding the Google account.
![]()
You can select all the GSC properties connected with your Google account.
![]()
Please be advised that you have enough permissions to your Google search console property to fully access the data.
# Wordpress
Source: https://docs.keywordinsights.ai/integrations/wordpress
#### Publish your content directly with a click of a button. No copy-pasting, no plugins, just seamless automation.
Creating high-quality content is only half the battle. Once it’s ready, the next hurdle is formatting, uploading, attaching images, adding authors, and hitting publish. Our WordPress integration eliminates that bottleneck. With a simple setup using your existing WordPress login (no extra plugins required), our Writer Assistant and Agent can automatically draft or publish your articles for you. Content, images, links, and all.
### How to use the Wordpress integration?
The Wordpress integration is available from our AI Writer Assistant and AI Writer Agent.
Click the "Publish" button from the top right hand corner.
![]()
Click "Connect to Wordpress"
Enter the following information.
![]()
1. Username: This is your Wordpress username
2. Application password: Generate a new application password.
3. Your website URL: The Wordpress website URL
Do not use your regular login password. Generate an Application password.
### How to generate an application password?
First, Login to your Worpress account.
Go to "Users"
![]()
Click and open the user.
Scroll down to "Application Passwords"
![]()
Under New Application Password Name, Give it a name. For example "Keywordinsights"
Click "Add New Application Password"
![]()
Copy this password and use it within the modal.
Please ensure you have the necessary permissions. You must have an Author, Editor, or Administrator role to connect a site.
# Freemium Tools
Source: https://docs.keywordinsights.ai/learning-center/freemium-tools/README
# SERP Analyzer
Source: https://docs.keywordinsights.ai/learning-center/freemium-tools/serp-analyzer
Instantly check live SERPs with our Free SERP Checker.
Our SERP analyzer tool helps you study search engine results pages to understand why certain websites rank higher. It analyzes factors like top-ranking pages, keywords, backlinks, and content structure, giving you insights to improve your SEO strategy and outrank competitors.
### What is the SERP Analyzer?
The SERP Analyzer is a powerful tool for anyone looking to optimize their website’s performance in search engine results. The tool analyzes the top-ranking pages for your target keyword and provides actionable insights that can help you improve your SEO decision making and help benchmark your site against the competitors.
We offer over 10+ important SEO metrics to help you quickly assess the competition and understand the content that’s ranking in the SERPs. Key data points include Moz DA, PA, backlinks, search intent, word count, publication date, and the number of referring domains, among others.
SERP Analyzer has 2 views.
1. Live SERP view
![]()
2. SERP Analyzer view
![]()
### How do I use the SERP Explorer?
To use the SERP Explorer, Head to the tools and click the link.
![]()
Fill in all the information.
![]()
1. Folder where your project belongs.
2. The keyword you want to search for.
3. Number of search results. You can choose between 10, 50 or 100.
4. Search location.
5. Search language.
6. Type of search, You can perform web, images, news, shopping, and video searches.
7. Device type. You can select between mobile, tablet or desktop.
8. Number of credits used/left.
9. Click the "Analyze" button to perform the search.
### Feature comparison table
![]()
### Do you have a free version of the tool?
A free, limited version of this tool will soon be available on our website’s landing page. No login required. Subscribers will enjoy a faster, feature-rich version with advanced capabilities.
# SERP Similarity
Source: https://docs.keywordinsights.ai/learning-center/freemium-tools/serp-similarity
SERP Similarity Checker will quickly show you the overlap between two keywords in the SERPs and tell you whether you should create a new page or can target multiple keywords with a single page.
This is a quick way to check if two keywords without having to use our keyword clustering module.
This insight will allow you to assemble content briefs faster and more efficiently.
### What is the SERP Similarity checker?
When working in SEO, you often encounter a situation where you quickly want to know whether you can rank two similar keywords on a single page or need to create a separate article.
The way to answer this question is to manually check the SERPs (Search engine results pages) to see how many common URLs rank for each keyword.
If we see a large number of similar pages ranking for both keywords, we can assume that both keywords can be targeted on a single page, and if we see a few common URLs, then we can assume these keywords need separate pages.
Here is an example.
In this example, there are 2 common URLs for the keywords "**crm too**l" and "**crm software**"
![]()
This tells you that these keywords are likely better off targeted using two separate pages.
### How do I use the SERP Similarity Checker?
This video is 5.52 minutes long.
To use the SERP Similarity checker, Head to the tools and click the link.
1. Give your project a name.
2. Enter your keywords here. You can add up to 6 keywords. (Depending on your subscription)
3. Select your location.
4. Select your language.
5. Click "Check Similarity"
You can also run bulk similarity checks. To do this, click "Add keyword set" to open a new window where you can put a different similarity-checking job. You can run up to 6 sets.
![]()
The results will be displayed as a visualization.
1. You can switch between different sets.
2. You can see SERP overlap between the keywords by turning the checkbox on and off.
3. This is where the common URLs are displayed.
4. This is where the overlap is visualized in a table format.
5. You can take a screenshot by pressing this button.
![]()
### Feature comparison table
![]()
### Do you have a free version of the tool?
A free, limited version of this tool will soon be available on our website’s landing page. No login required. Subscribers will enjoy a faster, feature-rich version with advanced capabilities.
# Title AI - (Blog Idea Generator)
Source: https://docs.keywordinsights.ai/learning-center/freemium-tools/title-ai-blog-idea-generator
Are you looking for some fresh blog ideas? Enter a keyword, and we’ll scrutinize the top 30 Google rankings, enhance them with AI magic, and promptly generate new blog ideas for you.
### What is the Title AI?
Title AI is a versatile blog idea generator designed to simplify content creation. When you're stuck and need new ideas, type in a keyword. Title AI instantly explores the SERP results for your selected country and language, providing a foundation to formulate unique content suggestions.
It leverages real-time data, ensuring that the blog ideas presented are proven to rank and serve as an innovative starting point for creators. The tool is user-friendly, making it a handy companion for anyone needing original, ranking-driven blog ideas.
![]()
### How do I use the Title AI?
### Feature comparison table
![]()
### Do you have a free version of the tool?
A free, limited version of this tool will soon be available on our website’s landing page. No login required. Subscribers will enjoy a faster, feature-rich version with advanced capabilities.
# Keyword Insights Tool Workflow
Source: https://docs.keywordinsights.ai/learning-center/keyword-insights-tool-workflow
Keyword Insights turns keyword research into a complete content system. Instead of bouncing between tools, you can go from discovery to clustering, briefing, and production in one place, with clear priorities based on what Google already rewards and what audiences are actually asking.
You can follow the workflow end to end, or jump into any stage depending on what you need today.
## **The workflow explained**
![Clean Shot 2026 01 29 At 17 13 41@2x]()
### **Step 1: Discover keyword ideas**
Begin with a seed topic and generate relevant keyword ideas related to it. This approach provides a comprehensive understanding of how people search, rather than just a few obvious terms. Moreover, the keywords are personalized to your workspace, ensuring that you only see those relevant to your workspace or business.
### **Step 2: Cluster keywords into topics**
Group keywords into topical clusters so you know which terms belong on the same page and which need their own content. This is how you build coverage without cannibalising yourself and how you map content in a way that supports topical authority.
### **Step 3: Create content briefs**
Turn clusters into SERP led briefs. Keyword Insights pulls from real time search results and other sources to help you create a brief that covers the angles that matter, aligns with intent, and makes writing faster and more consistent.
### **Step 4: Write with the AI Writer Agent**
When you desire a draft that is meticulously crafted from research, rather than relying on generic templates, the AI Writer Agent is an ideal choice. It automates in-depth research, identifies content gaps, and generates a publish-ready article based on your keyword and competitor analysis. Additionally, it writes in the style of your authors, who are trained on their writing style, thereby bypassing AI detectors.
### **Step 5: Get social mentions and rank in LLMs**
We showcase all the social opportunities available to your clusters, such as Reddit, YouTube, Quora, and so on. These platforms provide a natural environment for initiating conversations and promoting your brand. Moreover, these platforms are frequently cited by LLM models and featured in AI-generated responses, ensuring a seamless and non-spammy process.
# The Features
Source: https://docs.keywordinsights.ai/learning-center/the-features/README
# AI Writer Agent
Source: https://docs.keywordinsights.ai/learning-center/the-features/ai-writer-agent
### **What is AI Writer Agent?**
Our AI writer can do deep research, identify content gaps, find insights beyond the SERPs, Create content outline and write natural, engaging articles. The draft is optimized with relevant topics and entities, and is ready to publish. Though you can still review and edit it if needed.
### **How does our AI Writer Agent works?**
The agent starts with your keyword, runs keyword research and checks competitor pages to spot missing content. It also looks at other sources for extra ideas. Once done, it builds an outline and writes the article in clear, natural language. You can set the tone, length, and how different you want it to be. The entire process is fully automated.
### **What’s the difference between the Writer assistant and the AI Writer Agent?**
Our regular Writer assistant gives you full control over what you create. You manage the research, writing, and optimization yourself. In contrast, the Agent handles everything automatically using all available data and tools. It’s faster and hands-off, but you give up some control in the process.
### How do you go from Clustering to producing content?
We have significantly simplified the process so that you can go from a cluster output to content in a few clicks. You get to skip all the work and still maintain a good level of quality.
![]()
Here is a short demonstration
![]()
### Is AI content bad for SEO?
This is what Google say
*"Our focus on the quality of content, rather than how content is produced, is a useful guide that has helped us deliver reliable, high quality results to users for years."*
We built this agent with this in mind and our 'Add your own insights' feature will help make your content useful and valuable. Plus we pull data from multiple sources via our deep research agent.
![]()
You can include your own insights by enabling this option.
![]()
### What if multiple users enter the same keyword? Won’t the AI generate identical content for all of them?
Even if you use the same keyword multiple times, the output won’t be exactly the same. it will differ slightly with each run. That said, to make your content truly stand out and provide value, we recommend adding your own insights and expertise whenever you can.
### Which Content Type Should You Choose?
When using the AI Writer Agent, you can choose between two content types:
![]()
**Long-form article**
Use this to generate in-depth, comprehensive articles ideal for blog posts, educational content, thought leadership, and SEO-driven guides. The AI handles research, structure, and writing based on your keyword and preferences.
Example:
* [A Guide to Content Marketing in 2025](https://www.notion.so/A-Guide-to-Content-Marketing-in-2025-225d9493b17f801c89b8c2421a824a2c)
**Landing page**
Choose this option to generate conversion-focused landing pages for various business needs. This includes:
* Service pages
* SaaS product pages
* Local business landing pages
Examples:
* [Professional SEO Audits for eCommerce Sites](https://www.notion.so/Professional-SEO-Audits-for-eCommerce-Sites-Boost-Your-Online\[%E2%80%A6]-Performance-225d9493b17f80148f0ee8aeb69962de?source=copy_link)
* [Men’s Waterproof Jackets](https://www.notion.so/Men-s-Waterproof-Jackets-Premium-Rain-Protection-for-Every-Adventure-225d9493b17f808c97d6e6732033f38f?source=copy_link)
* [AI-Powered Content Brief Generator](https://www.notion.so/AI-Powered-Content-Brief-Generator-Create-High-Converting-Content-in-Minutes-225d9493b17f80f5b064c4cc65714272)
* [Expert Plumbers in Bromley](https://www.notion.so/Expert-Plumbers-in-Bromley-24-7-Emergency-Plumbing-Services-225d9493b17f80ea9f90ffc546d3d1e3)
This setup helps you create tailored content that matches your business goals and drives results. Whether you’re looking to rank, convert, or educate.
# Competitor Visibility
Source: https://docs.keywordinsights.ai/learning-center/the-features/competitor-visibility
Within your keyword cluster project, you can head to the competitor visibility tab to get a top-eye view of how your competitors are doing for that same group of keywords you've uploaded.
You have to do your keyword research, upload the keywords to the keyword clustering tab, and add your domain for tracking; we'll show you which competitors are doing better for your "target clusters" than you.
### How to use the feature.
Go to your clustering report and click "Competitor visibility."
![]()
The table view
![]()
The graph view
![]()
Venn diagram
![]()
**Here is the video explanation**
# Content Briefs
Source: https://docs.keywordinsights.ai/learning-center/the-features/content-briefs
Great content writing starts with excellent planning. And planning can be tedious.
Our AI-driven content brief application is designed to help you outline the perfect article quickly, effortlessly, and at scale.
### How do you use the content briefs?
# Keyword Clustering
Source: https://docs.keywordinsights.ai/learning-center/the-features/keyword-clustering/README
### **What is keyword clustering?**
Keyword clustering is the process of gathering similar keywords into groups. In essence, a "keyword cluster" is a collection of keywords that share the same meaning and intent, and thus, can be effectively targeted on a single webpage.
Upload your keyword list into Keyword Insights and we’ll analyse the search engine result pages to group any keywords together where the ranking URLs are the same or similar.
### **Why cluster keywords?**
1. **Take the guesswork out of content production.** When creating new content, it can be very difficult to know when a certain piece should be broken out into more specific sub-topics. For example, if we had the keywords "architect fees" and "how much do architects cost?" would you quickly know whether you need 2 different pages to target these, or if they could both be targeted on the same blog? Keyword Insights makes this quick and painless. We use live search results pages and group keywords based on what's ranking. So you’ll know, in seconds, when a page should be broken out into sub-topics to stand the best chance of ranking.
2. **Find gaps in your content quickly.** With the flick of a switch, we allow you to pull in your current rank and the ranking URL for each cluster. This will allow you to very quickly spot gaps in your content... It's just a case of looking for the clusters that don't rank (or rank poorly). View this guide for more information: [https://www.keywordinsights.ai/blog/content-gap-analysis/](https://www.keywordinsights.ai/blog/content-gap-analysis/).
### Why use Keyword Insights?
1. Firstly, Keyword Insights uses live, country-specific SERP data for each query.
In the keyword clustering process, we examine each keyword in the top 7 search results. If a keyword shares 40% or more URLs in common with others (a percentage you can modify in the settings), we classify them as a cluster. This method proves to be more accurate than using Natural Language Processing, a technique that many other clustering tools rely on.
View more on how our clustering works in the video below 👇
Why do you analyze 7 SERP results instead of 10?
Previously, we allowed SERP overlap settings between 1-10. However, due to the increasing number of SERP features (AI Overviews, Quick Answers, Featured Snippets, etc.), Google no longer consistently shows 10 traditional links in the top 10 results. This affected the accuracy of clustering, so we adjusted the threshold to between 1-7.
2. We cluster better. We understand every niche is different so we give you maximum flexibility with your keyword clustering settings. You're able to [adjust the URL overlap](the-advanced-settings/keyword-grouping-accuracy) (default is 40%), the type of clustering algorithm used and how strict the NLP is to form your [topical clusters](the-advanced-settings/topical-cluster-creation-method).
3. For each of the keywords uploaded into Keyword Insights, we pull through the [intent](../search-intent-context) so that you can easily work out what type of content (whether it be transactional or informational) for each cluster.
4. In our tool, you can select a target domain to monitor rankings for each keyword you upload. This means you can effortlessly upload thousands of keywords, have them grouped, and then quickly identify where your content might be lacking, all in just a few minutes. This process is outlined perfectly in [this guide](https://www.keywordinsights.ai/blog/content-gap-analysis/).
### How do I use the Keyword clustering feature?
This video is 9.48 minutes long.
### Keyword clustering is a 3 step process.
**Step 1**: Select your settings and project name. **Step 2**: Upload your keyword list(s), or select list(s) **Step 3**: Confirm and process your order.
### Step 1:
Launch the app and select your [Workspace](/utilities/workspaces), Then select Keyword clustering from the sidebar.
![]()
All of your settings and data will be pre-filled based on your Workspace settings (Country, Language, Domain etc)
![]()
**Select presets:** You can create presets for your clustering settings. So you can easily create or load previously saved settings. This saves you time in the future.
1. **Folder:** Choose an existing project folder or create a new one where you'd like to store the project. You will default to your Workspace folder.
2. **Project name:** Enter the name of your project. Be sure to use a clear naming convention to help you stay organized.
3. **Select preset:** You can save time by setting a favorite preset, which allows you to quickly apply your preferred settings every time. Presets can be created and saved in the Settings menu.
4. **Advanced Settings:** You change the SERP Overlap and Topical cluster creation method [here](/learning-center/the-features/keyword-clustering/the-advanced-settings/README).
5. **Get Rankings:** By Default the domain is set to your Workspace settings. (We'll track the rankings for all the keywords in your list. This will show you where you currently rank and help you quickly identify gaps in your clusters. It's a great way to establish a baseline for your existing content). With **Cluster ranking at different domain levels** - You can now track rankings for your cluster across different domain levels.
**Subdomains** - Default setting. Tracks everything.
**Exact URL** - Only tracks the exact URL.
**Path** - Tracks anything in the provided path.
**Domain** - Tracks only the specified domain. (Sub domains are not tracked)
6. **Get search intent** - Enable this feature to automatically detect and classify search intent for your keywords at both the keyword and cluster level. Learn more about it [here](../search-intent-context).
7. **Next** - Click here to continue.\
\
Note: **Location & Language:** Automatically selected based on your Workspace settings. (Selecting the correct location is essential for precise SERP clustering. Make sure the live search engine results align with your target area by choosing the appropriate location. For example, if you're targeting the United Kingdom, select 'United Kingdom' from the location dropdown, and we'll retrieve results from google.co.uk), Selecting the correct language is essential for accurate SERP clustering. To ensure the search engine results align with your target language, choose the appropriate language setting. For example, if you want to analyze SERPs in a different language within a specific country, adjust both the location and language accordingly. For instance, you can select "United States" as the location and "Spanish" as the language. Fine-tune your clustering results by optimizing both location and language settings for the most relevant insights.
### Why enable the Rank tracking feature?
This feature allows you to see which pages are ranking for each keyword within your cluster and identify the dominant or top URL for the entire cluster. You'll also get the average ranking position for the cluster, helping you quickly spot content gaps. Additionally, an "opportunity volume" metric is provided, which calculates the potential search volume gain based on your current rankings and the improvement you could achieve by focusing on that keyword cluster.
Having rank tracking can give you the following benefits.
1. **Ranking URLs:** See which page(s) is ranking for each keyword in your cluster.
2. **Dominant intent & Intent explanation:** See the dominant or the top URL for a given cluster and the actual intent explanation.
![Clean Shot 2026 01 26 At 10 19 21@2x]()
3. **Get the average position for the cluster:** If it's low or non-existent you'll quickly know where your content gaps are.
![Clean Shot 2026 01 26 At 10 18 25@2x]()
4. \*\*Opportunity volume calculation: \*\*The 'opportunity' is a unique metric where we examine the search volume of a group of keywords, consider your current ranking, and then estimate the remaining 'opportunity' if you decide to focus on improving your rank for that cluster of keywords.
![Clean Shot 2026 01 26 At 10 17 30@2x]()
5. **Intent mismatch detection:** We cand detect if your current top ranking page matches the clusters dominant intent.
![Clean Shot 2026 01 26 At 10 15 37@2x]()
6. **Keyword cannibalization detection:** We present all the ranking URLs in the top 100 results of Google search engine results pages (SERPs) for each keyword in your cluster. This allows you to identify similar pages ranking for the same cluster or pages with different intents. Consequently, you can make informed decisions regarding whether to merge or split pages.
![Clean Shot 2026 01 29 At 17 25 44@2x]()
![Clean Shot 2026 01 29 At 17 26 31@2x]()
### Why enable the Search Intent feature?
Enjoy the convenience of search intent classification, enabled by default for your clustering project. Our hybrid machine learning algorithm + LLM analyze each keyword in your list, swiftly identifying their intent. This feature enables you to isolate clusters that trigger informational content effectively. Elevate your clustering analysis with automatic search intent classification.
Note: Due to increased processing costs, we charge an additional credit for using the search intent feature.
![]()
### What's the difference in output with and without the search intent?
You will be able get the following additional insights when you enable search intent.
![Clean Shot 2026 01 29 At 17 28 30@2x]()
1. **Intent explanation:** We explain the actual intent of the cluster as perceived by Google.
2. **Opportunity volume** - Most tools see how much volume a keyword gets to create an opportunity score, but they don't take into account two important things:
1. A realistic number of visitors based on volume can be determined by looking at the [CTR study by AWR](https://www.advancedwebranking.com/ctrstudy/). Based on this study, if you rank in position 1, you can expect to get 38% of the clicks, position 2 gets 13%, position 3 gets 8% etc.
2. It doesn't consider where you currently rank (and, therefore, the opportunity).
So we calculate the opportunity score by doing the following.
If someone ranks in position 1 for a keyword, the opportunity score will be "0", as they already rank for it. However, if they rank in position 2, it will be the difference between the percentage scores of position 1 and position 2. So we have 1 column, "maximum opportunity", which is position 1 (or 38%) multiplied by the search volume. Then another column called "current estimated traffic", which is whatever their current position is, multiplied by the volume. So if we were in position two, it would be 13% multiplied by the volume. The opportunity is then the difference between the two.
For example, "cats" has a search volume of 100. We rank in position 3.
Maximum opportunity = 38 (38% x 100) Current Estimated traffic = 8 (8% x 100) Opportunity = 30 (30 - 8).
3. **Dominant search intent** - We start by clustering keywords based on SERP overlaps, then classify the intent for each keyword within the cluster. From there, we determine the dominant search intent for the entire cluster, which guides the type of content you should create to target that cluster effectively.
4. \*\*User Journey: \*\*We will map the user journey of the customer represented by the cluster. This involves using the contextual awareness of your brand and the workspace information.
5. \*\*SERP Features: \*\*We will extract any Google AI overviews and other key SERP Features appearing for this cluster.
![Clean Shot 2026 01 29 At 17 33 58@2x]()
6. **Recommended keyword** - The keyword highlighted in green is identified by our algorithm as the "best" keyword to send to the content brief or writing assistant, as it provides the most informative results for the cluster. This feature is available only if search intent is enabled for your project.
**Note:** With our latest [AI Writer Agent](../ai-writer-agent.mdx#how-do-you-go-from-clustering-to-producing-content), you can send this keyword directly for content production.
7. **Search intent for each keyword** -Because we classify intent for every keyword, you can easily spot keywords within a cluster that have a different intent. This insight can help you decide if you need to adjust the type of content that's currently ranking for those keywords.
By leveraging intent data, you can identify clusters that trigger informational intent. Easily eliminate any clusters that do not generate informational content, as working on them would be futile since Google will not rank them. Streamline your clustering efforts and focus on content that aligns with user intent for optimal results.
![]()
![<p>Demo of using the context filter</p>]()
You may make additional advanced changes to your settings by clicking the "Advanced toggle" You can read more about these settings [here](the-advanced-settings/).
7. Now the settings are done, we can move on to step 2 which is uploading the keywords. Click '**Next**'
### Step 2:
Click Upload file.
We allow multiple ways to upload your keywords.
1. **Local files** - This feature allows you to upload your own keyword and search volume data from other tools. You can upload multiple files, and we support both CSV and XLSX formats.
**Important:** You can upload up to 200,000 keywords per clustering project.
2. **From Keyword Lists** - If you use our Keyword Discovery feature to generate keywords, you can easily transfer the data here from the keyword lists without the need to upload it manually.
![Clean Shot 2026 01 29 At 17 38 26@2x]()
![Clean Shot 2026 01 29 At 17 39 12@2x]()
**Upload from a local file.**
Importing your CSV or XLSX is quick and painless. Upload your file and we’ll automatically detect and map the Keyword and Search Volume columns for you.
No reformatting required, even if the file came from a different tool. If anything looks off, you can adjust the column mapping in the next step.
Once it’s mapped, hit “Summary” and you’re ready to go.
![Clean Shot 2026 01 29 At 17 42 05]()
You can also bring your own Keyword Difficulty scores from tools like Semrush, Ahrefs, or Moz.
Here's how it works: Download your keyword data from your preferred provider, upload it to our clustering tool, and toggle "**I want to use my own KD**." Then, map your columns and select Keyword Difficulty alongside keywords and search volume.
You can upload multiple files and combine keyword data from multiple sources. This feature is incredibly handy when dealing with keyword data from various sources. You can simplify your workflow by uploading all your files at once and creating a unified, organized document ready for clustering.
Once the file(s) are uploaded, click **Summary**.
### Step 3:
The next and last stage will allow you to check your credit status and edit the project settings before you submit your order. Click "**Confirm order**".
1. **Project status.** Please note that your project will not process until you click 'Confirm order'
2. **Project settings** - Here is your last chance to review your settings.
3. **Time estimate** - This shows a rough time estimate.
4. **Credit information** - Shows your credit availability. Please note that we will always use your subscription credits first and PAYG credits after for clustering.
5. **Confirm order** - Click this to confirm your order.
![Clean Shot 2026 01 29 At 17 43 10@2x]()
Please note that the project **will not be processed** until you click "**Confirm order**"
The status will go from "**Confirmed**" to "**Processing**" and to "**Completed**."
![]()
You can go to Projects and find your processed file. You will also get an email with the link to your project.
Click the project when you see the status "**Finished**" to see the visualised results.
![Clean Shot 2026 01 29 At 17 53 09@2x]()
If you want to analyse the output in Google Sheets/Excel file, Click the three dots to download pre-pivoted Google Sheets from the projects or by clicking the 'Export' button from the clustering output.
![Clean Shot 2026 01 29 At 17 53 33@2x]()
We support both Excel and Google Sheets outputs. However, these have row limitations, and we recommend switching to CSV export for the raw file.
![Clean Shot 2026 01 29 At 17 54 32@2x]()
# The Advanced Settings
Source: https://docs.keywordinsights.ai/learning-center/the-features/keyword-clustering/the-advanced-settings/README
###
# Clustering Types
Source: https://docs.keywordinsights.ai/learning-center/the-features/keyword-clustering/the-advanced-settings/clustering-types
### We have multiple keyword clustering algorithms.
You can change the clustering algorithm in our advanced settings. Go to Keyword clustering and click the advanced settings toggle.
Select the algorithm.
![]()
### What are the keyword clustering algorithms and how do they work?
### Centroids
We take the keyword with the largest search volume and then group all other keywords which share x number of URLs in common with it from the top 7 (x can be changed by you, but it is set at 4 by default). All keywords in the group will have a common URL (the one with the highest search volume), but they won’t necessarily have common URLs with each other.
This method of clustering generally results in larger clusters.
### Agglomerative
All keywords are compared against one another and are clustered into a group if they share the x number of URLs in common from the top 7 (x can be changed by you, but it is set at 4 by default).
This method of grouping generally results in smaller, tighter clusters and takes a little longer to produce the report as every keyword is being compared against each other.
### Which algorithm should I choose?
#### Centroids Algorithm
**Advantages:**
1. **Simplicity and Speed:** This algorithm can be faster as it only compares keywords against one key term (the one with the highest search volume).
2. **Larger Clusters:** It generally creates larger clusters, which might benefit a user trying to create broad topics or themes.
**Disadvantages:**
1. **Lack of Nuance**: It may create clusters that are somewhat arbitrary or lack specificity because they're hinged on a single term.
2. **Missed Opportunities**: Some potentially relevant keyword clusters may be overlooked if they do not have enough commonality with the high-volume keyword.
**Choose the Centroids Algorithm if:**
* You're seeking larger, overarching themes or topics.
#### Agglomerative Algorithm
**Advantages:**
1. **Specificity**: It typically produces smaller, more precise clusters, which could be more relevant for targeted marketing or SEO campaigns.
2. **Holistic View**: As all keywords are compared against each other, it may uncover unique or unexpected keyword groupings.
3. **Thoroughness**: This algorithm can be more robust and reliable for forming tightly-knit, highly relevant clusters.
**Disadvantages:**
1. **Computational Intensity**: This approach may take longer for you to get your report.
**Recommendations for Customers**
Choose the Centroid Algorithm if:
* You want to identify broad topics or themes before focusing on specific areas.
* Use Case: Start by running 200,000+ keywords through the centroid algorithm to discover overarching topics you may not be covering. Once identified, you can then use the agglomerative algorithm to break down these broad themes into specific pages that need to be created.
Choose the Agglomerative Algorithm if:
* You seek accuracy and detailed insights into which pages need to be created.
For most customers and niches, the agglomerative algorithm will generally be the most useful starting point.
#### Recommendations for Customers
**Choose the Agglomerative Algorithm if:**
* You're working with a relatively smaller set of keywords.
* Uncovering unique and tightly-knit clusters is important to your strategy.
* You're willing to allocate more time for thorough analysis.
**For most customers, in most niches, we recommend sticking with the Agglomerative algorithm.**
### Why do we analyse only the top 7 organic results instead of 10?
In recent months, we’ve noticed that many search queries are increasingly dominated by SERP features like featured snippets, AI Overviews, people also ask boxes, and more. These elements are pushing traditional organic listings further down the page, often below the fold. As a result, the top 7 organic results now provide a more accurate representation of what users actually see and engage with. It’s a shift driven by how the SERP landscape has evolved and our analysis adapts accordingly.
# Keyword Grouping Accuracy
Source: https://docs.keywordinsights.ai/learning-center/the-features/keyword-clustering/the-advanced-settings/keyword-grouping-accuracy
### What is keyword grouping accuracy?
The minimum number of URLs in the SERPs required to group keywords. The selected grouping accuracy will influence the number of keywords in a single group. The higher the accuracy, the fewer keywords will be put into a single group.
By default, we use the value 3. It means if we see 3 common URLs for keywords, these keywords will be put into a single cluster.
e.g. Let's take these two keywords as examples.
**Keyword 1**: weight loss with shots
**Keyword 2:** weight loss with injections
For the keyword '**weight loss with shots**, the SERPs in the United States return the following top 10 results:
```text theme={null}
www.mayoclinic.org
www.cuimc.columbia.edu
www.cuimc.columbia.edu
www.medicalnewstoday.com
www.cuimc.columbia.edu
www.stylecraze.com
www.fda.gov
www.simply-slim.com
www.goodrx.com
www.wegovy.com
```
For the keyword '**weight loss with injections**' the SERPs in the United States return the following top 10 results:
```text theme={null}
www.fda.gov
www.goodrx.com
www.goodrx.com
www.saxenda.com
www.cuimc.columbia.edu
www.wegovy.com
www.goodrx.com
www.medicalnewstoday.com
www.scientificamerican.com
www.hopkinsmedicine.org
```
We can see that there are four common URLs
```
www.cuimc.columbia.edu
www.goodrx.com
www.medicalnewstoday.com
www.fda.gov
```
So, we will cluster/group these into a single cluster.
![]()
You can change the values in our advanced settings. Go to Keyword clustering and click the advanced settings toggle.
Important to remember, we look at the full ranking URL when clustering and not the root domain.
![Clean Shot 2026 01 29 At 17 56 40@2x]()
1. Toggle advanced settings
2. Select the [algorithm type](clustering-types)
3. SERP grouping accuracy
4. [Topical cluster strength](topical-cluster-creation-method)
# Topical Cluster Creation Method
Source: https://docs.keywordinsights.ai/learning-center/the-features/keyword-clustering/the-advanced-settings/topical-cluster-creation-method
Let's begin by defining the classification system of our clustering terminology.
* A [cluster](../#keyword-clustering) refers to a set of keywords grouped together based on their similarity.
* A topical cluster can be thought of as a "supercluster". A topical cluster is where we've "clustered the clusters" so to speak.
We give you "topical clusters" to expedite your understanding of the potential similarity among different clusters. Recognizing the topical similarity between clusters has multiple advantages.
1\) It simplifies planning your content calendar by ensuring you address all semantically related topics, thus establishing yourself as an expert, or a topical authority, in that area. For instance, consider the clusters: "How to do keyword research for Amazon", "Best keyword research tools for Amazon", and "How to do competitor keyword research for Amazon". By grouping these together, you can efficiently plan your content calendar, optimising internal linking from the beginning and ensuring comprehensive coverage of a topic.
2\) Additionally, understanding these groupings facilitates the planning of your site's information architecture. Since we cluster "semantically similar" topics together and visually present this, you can more quickly draft your site's structure. This includes identifying inter-page links, main categories, and how everything interrelates.
In the screenshot below, you will quickly see about 15 "clusters" all grouped together within 1 big cluster.
![]()
You can't quite make it out here, but examples of some of the clusters include:
* How to do keyword research for Amazon
* Best Amazon Keyword research tools
* How to do affiliate keyword research for Amazon
Amongst some others.
As you'll notice, these are all clusters related to "keyword research" and "Amazon", but are all slightly different in their intent. Each will need its own separate article. Basically, we've made it really easy for you to plan and become a "topical authority" on "Keyword research for Amazon" by grouping all the related topics you need to cover together.
To use the topical clusters effectively it's also important to understand how they work and how they differ from the regular clusters.
* A standard cluster is formed by examining the search results for each keyword. Keywords are grouped together if they share a certain number of URLs, which you can define in the settings. By default, this number is 3, meaning that if a keyword shares at least 3 URLs with another keyword in the top 10 results, we group them together. Because we use real-time search results, the report you receive *can't* be wrong. It may not always be what you expected, but it literally does what we state it does.
* To create the bigger groupings, or topical clusters, we use Natural Language Processing (NLP). Think of NLP as a way for computers to understand human language. It looks at the clusters and groups them together if they are about similar topics (hence the name "topical clustering"). Because the range of keywords you might add can be very wide, we provide you with three different settings to adjust the results based on what you want. These settings are called soft, medium, and hard. Without getting too technical, the soft setting groups together clusters that are about 70% alike according to our computer analysis. The medium setting groups together clusters that are around 88% alike. The hard-setting groups clusters that are about 93% alike. This way, you can choose how closely related you want the topics in each group to be. Because we're using NLP, the results may vary wildly depending on what your setting is and may or may not be that useful depending on your desired goal.
Just to clarify, the "topical clusters" might not always be beneficial for your specific needs. They're designed to help you quickly group related content ideas based on topic similarity. However, the results shouldn't be viewed as a "finished picture". If you're using them to plan your information architecture or plan your "hub and spoke" content, you'll still likely have to do a bit of manual cleaning up.
Also, given that it uses NLP, the system might sometimes find it challenging to understand acronyms or intricate medical or technical terms. So, if your keywords heavily rely on such language, the results might not meet your expectations fully.
### **So what settings to use?**
The goal of our topical clustering tool is to group related clusters together based on their topic similarity. You should, therefore, adjust the settings according to the types of keywords you're working with and the outcome you wish to achieve.
Let's say you're researching keywords for a large sports website and plan to upload all the keywords at once. It might be helpful to use the "soft" setting, making it more likely that similar sports keywords will group together. For instance, all rugby-related clusters could form one topical cluster, with separate clusters for golf, tennis, and soccer.
On the other hand, if you're only uploading rugby-related keywords, the soft setting might not be as useful since it could result in one large cluster of all things rugby whereas you need the topic of "rugby" to be broken out into more granular subtopics. In this case, you might want to use the "hard" setting. This setting ensures that clusters are grouped together only if they are at least 93% similar in meaning. In theory, this should result in more specific topic clusters such as rugby clothing, rugby teams, rugby tactics, etc.
In summary, if your focus is more specific or the keywords you're uploading are very closely related, you might want to use a harder setting for more detailed clusters. For most projects, we recommend starting with the medium setting. You can always check the results and then rerun the process using the hard or soft setting, if necessary.
### **Where to adjust the settings?**
Once you've logged into the dashboard and navigated to the keyword clustering module, you'll find the topical clustering settings under the "advanced tab".
Simply change the value by pressing + or -
![]()
To view our documentation on how to use the topical clustering report in your strategy click[ here.](https://docs.keywordinsights.ai/understanding-the-output/how-to-interpret-topical-clusters)
# Keyword Discovery
Source: https://docs.keywordinsights.ai/learning-center/the-features/keyword-discovery
Reduce your reliance on other paid tools and carry out your complete keyword research all within Keyword Insights.
Keyword Discovery lets you quickly input a seed keyword and generate hundreds of related and similar terms.
These keywords can then be easily put back through our clustering algorithm, so you know which pages and how many pages you need to create to cover a topic comprehensively. All without leaving Keyword Insights.
### Feature Demo
### How to use Keyword Discovery in 4 steps?
### Step #1
Type your seed keyword and select location and language. Click search.
![]()
After a few seconds, we will bring you thousands of relevant keywords for your seed term.
With the seed keyword search, you'll land on the overview page, designed to provide valuable keyword insights and SERP intelligence.
This helps you assess whether the topic is worth pursuing. Within this section, you can gauge the keyword's competitiveness and trending patterns. It's your go-to place for making informed decisions about your content strategy.
![]()
1. **Keyword overview**: This shows the average monthly search volume for the seed term and the keyword list.
2. **Keyword trend:** This shows the Google trends data for the seed term.
3. **SERP preview**: This shows a real-time render of the actual SERPs for the seed term.
**Where are the keywords coming from?**
We will use different numeration methods to get keywords from the Google autocomplete feature for your seed term, balancing the quantity and quality/relevancy of the seed term.
### Step#2
The next step is to apply filters to fine-tune the results.
We have two ways to filter keywords.
1. Manual filters
2. AI smart filter (This feature is currently under maintenance)
**Manual filters**
Use this option to apply filters manually. Click 'Filters'
![]()
### Step#3
### What do I do after using Keyword Discovery?
The next step is to get search volume for your keywords. There are 2 ways to do this.
1. Use keyword insights built-in search volume module. We will get search volume, CPC, competition and trend data from Google keyword planner. It will cost you one credit per keyword to use this module.
2. You can export your keywords to any of your favourite SEO tools (e.g., Ahrefs) and get your search volume. Once you have the data, go directly to our[ keyword clustering module](keyword-clustering/#step-2) and upload your file.
How do you use Keyword insights to get search volume data?
Select the keywords for which you want to calculate search volume and click the search volume button in the floating bar.
![]()
![]()
Click the 'Get Search Volume' button to get search volume data.
![<p>You will be shown how many credits will be used and to confirm the credit usage. </p>]()
The output will look like this.
![]()
You can also get search volume for all the keywords by clicking the button at the top.
![]()
### Step#4
The last step is to cluster your keywords.
The cluster button will become available once you have search volume data for your keywords. Click this button and open the modal for cluster project settings.
![]()
Fill in the details and submit your project for clustering.
![]()
Go to your Projects -> Keyword clustering to find your processed clustering order.
![]()
### What's next?
The next step is to [analyse the clusters for opportunities. ](broken-reference)
### What other things can you do using Keyword discovery?
1. Check [SERP Similarity ](../freemium-tools/serp-similarity.mdx#what-is-the-serp-similarity-checker)
2. Analyze SERPs using [SERP Explorer](../freemium-tools/serp-analyzer.mdx#what-is-the-serp-explorer)
### What locations and languages do Keyword discovery support?
We support all locations and the following languages.
* English
* German
* Spanish
* French
* Dutch
* Danish
* Portuguese
* Norwegian
* Arabic
# Search Intent
Source: https://docs.keywordinsights.ai/learning-center/the-features/search-intent-context
Some keywords are explicit in their intent; usually, these are keywords with modifiers appended or prepended to them. Example include:
"Buy", "where", "how", "when", "coupons" etc.
But what does someone want to view when they search for something without any modifiers? What sort of content should we optimise for if the keyword is just "dogs"?
We use AI to quickly identify the search intent behind keywords at scale. Simply upload your list and we'll tell you, out of the top 10 results on Google, how many of the results are informational vs how many are transactional vs how many commercial vs how many are some other type of content.
### **Why do you call it "context" and not "intent"?**
Our competitors often talk about intent, whereas we call our insight "context". We do this because our metric works slightly differently.
When we talk about context, we mean “what is the contextual setting around this keyword?”. Let's use the example of “CBD Oil” as a keyword. On first impressions, we'd probably guess that intent behind such a keyword is transactional/commercial; surely if you search "CBD Oil" you want to buy it right? Other tools often classify the intent of that keyword as such.
![]()
Enter “Keyword Context”. If you actually witnessed the SERPs for that keyword, you’ll notice a lot of the results tend to favour more “long-form” type and not “product pages”.
![]()
This is where our metric, keyword context comes in. For the keyword “CBD Oil”, Keyword Insights would show you that the majority of results on the search engine result page are informational.
![]()
![Google sheets view]()
Using the above data, we can determine the most dominant intent for a given cluster. This helps us understand what type of content to create. (Whether it's an article, commercial page or a product page)
![]()
Once clustering is completed, you can easily filter your clusters.
![]()
We also offer an "Identify Intent" feature, which analyzes the SERPs for the main term of your cluster to determine the search intent for the entire cluster.
![]()
The intent behind the above keyword is “transactional”, but the context of it, currently, is “informational”, so you should create content that is informational in nature.
### **What are the type of intent available?**
We currently offer 4 types of intent classifications.
1. **Informational** - The user is looking for information or answers to a question. They aren’t necessarily looking to make a purchase but are seeking knowledge or insights. For example, a search like “how to improve SEO rankings” indicates informational intent.
2. **Commercial** - The user is interested in exploring products or services but hasn’t made a final decision yet. They may be comparing options or researching before making a purchase. For example, “best SEO tools” is a commercial intent query.
3. **Transactional** -The user is ready to take action, usually to make a purchase or complete a specific task. They’ve done their research and are now looking for a way to execute, such as “buy SEO software” or “buy cbd oil.” We usually classify product and product category pages.
4. **Other** - These are pages that don't fall into any of the above. Usually a home page, terms and conditions etc.
### How to use the Context feature?
The context (intent) toggle is enabled by default when running a clustering project.
![]()
### What languages are supported by Context?
We currently support **all** languages.
# Topical Clusters
Source: https://docs.keywordinsights.ai/learning-center/the-features/topical-clusters
Once you have your keyword clusters, it may be helpful to know how closely related those clusters are to other clusters. We apply NLP to find the semantic relationship between the clusters.
In addition to clustering your keywords, we apply Natural Language Processing to "cluster your clusters" so to speak.
This allows you to view how similar specific clusters are to one another so that you can easily plan and create content.
### What is the purpose of the topical cluster report?
Each specific area can be further dissected. For instance, under "how to do keyword research for Amazon", you might create content that provides a general overview, another piece reviewing the best research tools, and a third focusing on tracking down competitor keywords on Amazon.
The topical cluster report is here to simplify this intricate process. It identifies and groups related topics (clusters) together, aiding you in organizing your content and ensuring that you cover each topic thoroughly and logically, making your journey to becoming a topical authority smoother and more strategic.
Take a look at the screenshot below. You will quickly see about 15 "clusters" all grouped together within 1 big cluster.
![]()
You can't quite make it out here, but examples of some of the clusters include:
* How to do keyword research for Amazon
* Best Amazon Keyword research tools
* How to do affiliate keyword research for Amazon
Amongst some others. As you'll notice, these are all clusters related to "keyword research" and "Amazon", but are all slightly different in their intent. Each will need its own separate article.
To summarise, the "topical cluster" report groups similar clusters together. This should make it really easy for you to plan and become a "topical authority" on a given subject by grouping all the related topics you need to cover together.
**PLEASE NOTE:** The topical clusters report uses NLP to group similar clusters together. So depending on your niche, and the settings you apply, they may not always be useful. Your results will vary. As with any tool, this feature is designed to speed up your processes but it will not be perfect. A large part of your success also depends on the types of keywords you upload. Please read more about the advanced settings which you should use [here](https://docs.keywordinsights.ai/learning-center/the-features/keyword-clustering/the-advanced-settings/topical-cluster-creation-method).
**How to get the report:** The topical clusters report happens automatically as part of every clustering project, so it isn't a setting you need to select. However, as mentioned above, you can adjust the settings as you're creating the project.
You will find the topical clusters report within the cluster project here👇
![]()
You can either view them in a table or the bubble format as above.
Alternatively, you can export a Google Drive or Excel report as per the screenshot below 👇
![]()
Where the output will resemble a pivot table similar to the "table" within the UI.
![]()
To view our documentation on how to use the topical clustering report in your strategy click[ here.](https://docs.keywordinsights.ai/understanding-the-output/how-to-interpret-topical-clusters)
# Writer Assistant
Source: https://docs.keywordinsights.ai/learning-center/the-features/writer-assistant
Our Al-powered writing assistant is more than a tool; it's your writing coach. It streamlines your process, allowing you to research, write, and optimize on one platform. With its proprietary grading metrics, it offers valuable insights and continuously fine-tunes your work.
It's your all-in-one writing companion, from creating engaging paragraphs to switching tones, rewording sentences, and generating metadata. Discover a smarter, quicker, and easier way to write.
# Building service level pages
Source: https://docs.keywordinsights.ai/tool-use-cases/building-service-level-pages
**Video tutorial**
Here is the prompt.
`I'm creating a service landing page to target the query: "`*`Expat Tax Advice"`*`. Outline the key headings I should have on this page and include bullet points under each heading to make it easier for me to understand what to write. At the end, include some important FAQs I may wish to include.`
# Find Intent Misalignment
Source: https://docs.keywordinsights.ai/tool-use-cases/find-intent-misalignment
# Finding Content Gaps
Source: https://docs.keywordinsights.ai/tool-use-cases/finding-content-gaps
# Finding Keyword Cannibalisation (Case study 1)
Source: https://docs.keywordinsights.ai/tool-use-cases/finding-keyword-cannibalisation-case-study-1
"Keyword cannibalization" refers to the circumstance in which multiple web pages on the same site compete with each other for ranking in search engine results due to targeting the same or similar keywords. This unintentional competition dilutes the SEO impact of the pages, potentially diminishing the website’s overall performance and visibility in search engine rankings, especially prevalent in large platforms like e-commerce or travel websites where numerous similar pages might exist.
We recently increased a client’s website by 110% by reducing keyword cannibalisation 🚀.
Read the full case study here: [https://www.keywordinsights.ai/blog/keyword-cannibalization-case-study-no-1/](https://www.keywordinsights.ai/blog/keyword-cannibalization-case-study-no-1/)
# Finding Keyword Cannibalisation (Case study 2)
Source: https://docs.keywordinsights.ai/tool-use-cases/finding-keyword-cannibalisation-case-study-2
"Keyword cannibalization" refers to the circumstance in which multiple web pages on the same site compete with each other for ranking in search engine results due to targeting the same or similar keywords. This unintentional competition dilutes the SEO impact of the pages, potentially diminishing the website’s overall performance and visibility in search engine rankings, especially prevalent in large platforms like e-commerce or travel websites where numerous similar pages might exist.
We were able to quickly identify many instances of keyword cannibalisation on a client's blog site but using keyword clustering 🚀.
Read the full case study here: [https://www.keywordinsights.ai/blog/keyword-cannibalization-case-study-no-2/](https://www.keywordinsights.ai/blog/keyword-cannibalization-case-study-no-2/)
# Finding Reddit Opportunities
Source: https://docs.keywordinsights.ai/tool-use-cases/finding-reddit-opportunities
Get Your Brand Seen In LLMs With Social Mentions including Reddit, Quora and YouTube
When you run a clustering report, the output now highlights if your keywords/cluster trigger social links like Reddit, YouTube or Quora.
So this gives you an opportunity to get your brand mentioned in these social channels and communities.
But, why getting brand mentions in these channels is important?
According to a [study](https://www.statista.com/statistics/1620335/top-web-domains-cited-by-llms/) by Statista in collaboration with Semrush, Reddit was cited in around 40% of analyzed cases. This is likely tied to content licensing deals that make Reddit a key source for AI model training. YouTube followed with 23.5%, while sites like Quora came in at 4.6%.
The takeaway is simple. If you want your brand to show up in models like Gemini, ChatGPT, and Perplexity, your brand name needs to be mentioned across these social platforms.
That is why we are rolling out our new feature
Whenever you run a clustering project, we will automatically detect if any of the major social platforms are present in the SERPs for your clusters. This gives you two opportunities. First, you can create content around those clusters. Second, you can join the conversations that are already ranking in the top ten results for your keywords and make sure your brand becomes part of those discussions. Just remember, this is not about spamming. Always check the rules, respect the community, and add real value.
# New file
Source: https://docs.keywordinsights.ai/tool-use-cases/test
Description of your new file.
Hello testing
# Uncover Keyword Opportunities
Source: https://docs.keywordinsights.ai/tool-use-cases/uncover-keyword-opportunities
# How to Interpret Clusters in Google Sheets
Source: https://docs.keywordinsights.ai/understanding-the-output/how-to-interpret-clusters-in-google-sheets
Unlock the power of your keyword clusters with this informative video on interpreting cluster insights in Keyword Insights' using Google sheets. Learn how to gain deeper insights and make informed decisions with keyword data..
# How to Interpret Clusters with In-app Visualizations
Source: https://docs.keywordinsights.ai/understanding-the-output/how-to-interpret-clusters-with-in-app-visualizations
Unlock the power of your keyword clusters with this informative video on interpreting cluster insights in Keyword Insights' new in-app visualizations. Learn how to gain deeper insights and make informed decisions with keyword data.
Here is a video tutorial on how to interpret the output
What does the green highlight mean in cluster visualization?
When we group keywords together, we carefully analyze each cluster and select the most suitable keyword to focus on for content writing. Our algorithm takes into account various factors such as SERPs, CTR, Intent etc. By clicking the icon, you can easily add this keyword to your brief or writer assistant.
![]()
# How to Interpret Context/Intent
Source: https://docs.keywordinsights.ai/understanding-the-output/how-to-interpret-context-intent
Where possible, we recommend selecting the "context", or intent, feature within the clustering tool
![]()
When this is selected, each keyword you provide will be analyzed by our machine learning models to understand the purpose or 'intent' behind it. For instance, with each keyword uploaded, we'll inform you if the resulting content is primarily transactional, informational, or of a different page type. We use the term "context" instead of "intent", a term used by some of our competitors, to highlight the uniqueness of our approach. Our method often yields more precise results in terms of what you, as a user, are searching for. It considers the 'contextual setting' surrounding the keyword. For more information on this, you can read our blog here: [https://www.keywordinsights.ai/blog/keyword-context/](https://www.keywordinsights.ai/blog/keyword-context/) on what keyword context is.
There are multiple ways to interpret and use the results. It's perhaps best to show you how to use it within the exportable spreadsheets first as it'll make it easier to understand how the "context" is worked out and how you should use it.
If you download or open up the Excel or Google Sheets file, in one of the tabs you'll see each keyword on a separate row with 3 important columns in. These columns are "Article", "Product/Category" and "Other page type".
![]()
Each column contains a figure indicating the number of top 10 search results related to that page type. For instance, if you see the keyword "keyword research" with a '6' under the "article" column and a '4' under the "Product" column, it means that 6 out of 10 results are informational and 4 out of 10 results are transactional. In such a situation, the results are fairly mixed, but "informational" is the dominant intent. This suggests you could create both a product page and an informational page using this keyword without undermining your own SEO efforts, but an informational page is more likely to rank higher. Therefore, your focus should primarily be on creating informational content.
When you view this in the pivot table tab, you're simply seeing the "average" of all the keywords in that cluster.
![]()
Now you know how it works, let's take a look at it in the UI of the tool.
If you're in the UI, you can simply select the "context" filter along the top row and filter the clusters by their "dominant" intent.
![]()
Whether you're in the UI, or using the export, there's a wide range of use cases for being able to filter the clusters by their intent.
* If you've also pulled in the rank of your target domain, you can easily apply a filter within the UI to only show you informational clusters that your target domain doesn't rank for (or ranks poorly for). This gives you your "content gap". You can read more about that in our guide here: [https://www.keywordinsights.ai/blog/content-gap-analysis/](https://www.keywordinsights.ai/blog/content-gap-analysis/)
* If you're using the Google Sheets or Excel version, you can apply a filter on the sheet to look for all the keywords with "fragmented intent". I.e. those that are split more equally between transactional and informational results. You can then formulate an entire SEO strategy on ranking twice in the SERP results (once with a product page and once with an informational one) without fear of cannibalizing yourself.
* Within the UI, you can navigate to the "topical clusters" tab, and change the bubbles to be coloured by context, and get a very visual idea of whether your SEO strategy is going to be largely content-based or optimising product pages. See image below.
![]()
Here is a video that shows how to interpret the Context/search intent produced by Keyword Insights.
# How to Interpret Topical clusters
Source: https://docs.keywordinsights.ai/understanding-the-output/how-to-interpret-topical-clusters
Here is a video that shows how to interpret the hub/spoke model insight produced by Keyword Insights.
# How To Build Keyword Lists
Source: https://docs.keywordinsights.ai/user-guide/how-to-build-keyword-lists/README
Building an effective keyword list is an important part of using Keyword Insights.
In this tutorial section, you will learn how to build keyword lists using various 3rd party tools and our own keyword discovery module.
# Google Search Console (Integration)
Source: https://docs.keywordinsights.ai/user-guide/how-to-build-keyword-lists/google-search-console-integration
### How to use Google search console integration to automatically import keywords?
### Google search console demo
Get started by navigating to [Keyword discovery](https://app.keywordinsights.ai/keyword-discovery)
![]()
1. Select Google search console.
2. Click Add to add a new Google account.
3. Select a GSC property.
Tip: You need to verify your search console property to gain access or must have access to a pre-verified account. Also select the sc-domain property to access all the features such as graphs etc.
Click 'Import'
![]()
Depends on the number of keywords in the GSC property. it may take some time to import everything.
![]()
Once all the keywords are imported you can access the data.
![]()
1. Access filters.
2. Graph showing your GSC data.
3. Shows number of clicks, impressions etc.
4. Keywords column.
5. Quick search volume fetch option.
6. Average search volume column.
### Watch the interactive demo video below on how to use this feature.
# Google Search Console (Manual)
Source: https://docs.keywordinsights.ai/user-guide/how-to-build-keyword-lists/google-search-console-manual
### How to build keyword lists using Google search console
First, you need to access your search console account by going to [https://search.google.com/search-console](https://search.google.com/search-console)
Note: You need to verify your search console property to gain access or must have access to a pre-verified account.
Select the correct web property and click "´'Search results'
![]()
You will see all the keywords the website is ranking for listed here.
![]()
1. Date range - Google provides 16 months of data.
2. Queries - All the keywords.
3. Export button.
You can click 'Export' and download your CSV file.
To get more specific keyword data, you need to apply filters.
In this example, To find all the keywords a particular blog post ranking for.
To do this, click the + sign to bring up the filter popup.
![]()
Now click 'Page', Input your blog URL.
![]()
Change the filter to 'Exact URL'
Note: You can apply Regex and filter combinations to manipulate your data.
![]()
1. Your applied filter.
2. Filtered keywords based on the search criteria.
Download your CSV file, and you will get all your keywords.
But, you will not get the monthly search volume from the search console.
There are several ways to get this.
1. Google keyword planner (Free - But requires a paying Google Ad account)
2. Semrush/Ahrefs subscription.
3. Keyword everywhere subscription.
#### How to get monthly search volume data using the Google keyword planner.
First, we must copy all the keywords downloaded from the Google search console. Do this by opening the file with Excel/Google sheets.
Go to Google ads keyword planner (Refer to [this tutorial](using-google-keyword-planner) on how to access keyword planner)
Click 'Get search volume and forecasts'
![]()
Paste your keywords or upload the CSV file.
Click 'Get started'
![]()
You will get monthly search volume for your keywords.
**Note:** Not every keyword you upload will get a search volume result.
![]()
Now we need to export this data. The next step is important.
Click the download icon and be sure to select CSV under 'Plan historical metrics'
![]()
Now go ahead and upload the file to Keyword insights. :thumbsup:
#### How to get monthly search volume data using the Semrush/Ahrefs
Login to your paid Semrush account.
Navigate to 'Keyword Manager'
![]()
Give your keyword list a name, Click 'Create list', Once created, click the list name.
![]()
Click the 'Add keywords" button on the top. You can only add 1000 keywords per list.
![]()
Select the country and click 'Add keywords'
![]()
1. Your uploaded keywords.
2. Monthly average search volume.
3. Filters to further narrow your keywords.
4. Export button.
Click the export button to download the keywords with search volume.
Now go ahead and upload the file to Keyword insights. :thumbsup:
#### How to get monthly search volume data using Keyword Everywhere.
Keyword Everywhere is an affordable tool which enables you to extract metrics such as search volume.
The tool is credit based and well-priced. (\$10 for 100k credits)
Once you have a paying account, you need to download and install the extension.
Launch the extension and click 'Bulk Keywords Data'
![]()
Now, paste your GSC keywords in the box and click 'Get metrics'
![]()
Your results will be displayed in a table format.
You can see the monthly search volume assigned to your search console keywords. You can apply filters as necessary to narrow down your search and download your CSV/excel file.
![]()
Now go ahead and upload the file to Keyword insights. :thumbsup:
# Using Ahrefs/Semrush
Source: https://docs.keywordinsights.ai/user-guide/how-to-build-keyword-lists/using-ahrefs-semrush
### How to generate keywords from third-party tools (Video)
### How to build keyword lists using Semrush
Semrush is a popular SEO tool with an extensive keyword database.
You must have a paid account to use this feature. Prices start at \$119.95 /month.
Login to your Semrush account and go to the search bar at the top left-hand corner.
Type in your keyword, domain or the URL prefix/path.
![]()
You will get a result page like this.
![]()
1. Country - Select the country here.
2. Device - You can select between desktop or mobile.
3. Date - You can choose a time frame.
4. Clicking this will take you to all the keyword results.
5. Clicking this will take you to all the questions around this keyword.
6. Clicking this will take you to related keywords.
For this demonstration, I will click option 4.
Results display as follows.
![]()
1. Filter keywords by search volume - We recommend filtering by descending.
2. Select whether you want to apply a phrase or exact match.
3. Semrush breaks down the keywords by words, and you can easily group keywords by theme here.
4. You can apply other filters such as include and exclude keywords.
5. You can export the filtered data as a CSV.
Now go ahead and upload the file to Keyword insights. :thumbsup:
Note: Repeat the same process by inputting a domain or URL prefix and pulling in the keywords.
### How to build keyword lists using **Ahrefs**
Ahrefs is another popular SEO tool with an extensive keyword database.
You must have a paid account to use this feature. Prices start at \$99 /month.
Head over to [https://app.ahrefs.com/keywords-explorer](https://app.ahrefs.com/keywords-explorer)
Input your seed keyword, select the country and hit the search button.
![]()
Your results will be displayed as follows.
![]()
It's similar to Semrush. Click any of the organic keyword links to preview the data.
![]()
1. Switch between all keywords and questions.
2. Timeline.
3. Keywords grouped by word.
4. Additional filters such as include/exclude keywords.
5. Export button - Click this to download your CSV file.
Note: Repeat the same process by inputting a domain or URL prefix and pulling in the keywords.
Now go ahead and upload the file to Keyword insights. :thumbsup:
# Using Google Keyword Planner
Source: https://docs.keywordinsights.ai/user-guide/how-to-build-keyword-lists/using-google-keyword-planner
This tutorial will teach you how to build a strong keyword list using the Google keyword planner tool.
Note: You need an active and paying Google Ads account to get accurate search volume data. Without an active account, Google will only give you search volume estimates.
First, go to ads.google.com, Click 'Tools and settings' and select 'Keyword Planner.
![]()
You will see two options. Select 'Discover new keywords'
![]()
You will see two options again.
![]()
1. **Start with a keyword** - You input and get many related keywords.
2. **Start with a website** - You input a URL and find all the keywords for which the URL is ranking.
### Start with keywords.
Let's type in a couple of keywords.
Select the country and language and click the 'Get results' button.
![]()
You will see the search results. We recommend you take some time to clean up the results.
In this example, Google keyword planner shows us over 1800 keyword ideas.
![]()
1. You can set the date range here. If you want the newest data, you should set this to a recent time frame.
2. You can broaden your search by adding the keywords generated by Google. It's particularly useful when you have long tail or unpopular keywords.
3. The number of available keywords from your search.
4. Keyword
5. Search volume
6. Advanced filters - Using these filters, you can narrow down your keywords. You can apply things like brand vs non-brand, topical relevancy and many other suggestions Google provides.
7. After you have cleaned up your list, click this button to download your CSV file.
Note: Keyword Insights requires you to upload a file with the keyword and search volume columns, and you can map these columns easily. It means you don't have to tweak the downloaded CSV file, and It's ready for keyword insights.
Now go ahead and upload the file to Keyword insights. :thumbsup:
### Start with a website.
Put your URL prefix or root domain into the search box.
![]()
In this example, I added a URL prefix instead of a domain and selected the 'Use only this page' option. I want to find out all the keywords this URL is ranking for.
The results are displayed as follows. You can apply filters and download the CSV file.
![]()
Now go ahead and upload the file to Keyword insights. :thumbsup:
# Using Keyword Discovery
Source: https://docs.keywordinsights.ai/user-guide/how-to-build-keyword-lists/using-keyword-discovery
### How do you use Keyword Discovery?
Keyword Discovery lets you quickly input a seed keyword and generate hundreds of related and similar terms using different sources such as Google autocomplete, Quora, People Also Asked, etc.
These keywords can then be easily put back through our clustering algorithm, so you know which pages and how many pages you need to create to cover a topic comprehensively. All without leaving Keyword Insights.
### How do you use Keyword Discovery?
Start with your **Seed keyword.**
Type your keyword and select location and language. Click search.
![]()
After a few seconds, we will bring you thousands of relevant keywords for your seed term.
![]()
With the seed keyword search, you'll land on the overview page, designed to provide valuable keyword insights and SERP intelligence.
![]()
This helps you assess whether the topic is worth pursuing. Within this section, you can gauge the keyword's competitiveness and trending patterns. It's your go-to place for making informed decisions about your content strategy.
1. **Keyword list:** This shows you all the related keywords for your seed term.
2. **Keyword Google trend:** This shows the Google trends data for the seed term.
3. **Live SERP preview:** This shows a real-time render of the actual SERPs for the seed term.
The next step is to view all the keywords. Click the "View All Keywords' button to see the keyword list.
![]()
This is your keyword results view. You can switch between different sources such as Google Autocomplete, Quora, PAA, etc.
You can quickly get the search volume of your keywords, as well as CPC, competition, and trend data. You can use credits for this data. Each keyword costs a single credit.
Click the "Get search volume" button to quickly get search volume data for all the keywords.
![]()
Now, you can cluster keywords.
![]()
To cluster the keywords, click the "Cluster keywords" button.
Select your settings and click 'Cluster'
![]()
Once the clustering is completed, you will get an email and you can find it under projects.
We recommend you clean/filter your keywords before you get this data.
We recommend you apply filters to fine-tune the results
Use this option to apply filters manually. Click 'Filters'
![]()
Please note that filters can only be applied from the "All Keywords" tab.
### What do I do after using Keyword Discovery?
The next step is to cluster the keywords. This can be done easily with a click of a button.
After your keyword selection, click the "Cluster" button.
Fill in the details and submit your project for clustering.
# How To Get The $1 Trial
Source: https://docs.keywordinsights.ai/user-guide/how-to-get-the-usd1-trial
### What's included in the \$1 trial?
If you want to try out our platform before committing to a monthly or annual subscription, we have a \$1 trial for 7 days. With this trial, you'll get the following:
* 5000 Universal credits (Can be used against different features but locked
* Search intent classification and rankings (Part of clustering enabled by default)
* Clustering: Up to 500 keywords with intent + rankings
* One Content brief
* One AI Assisted Writer assist
* One AI Writer Agent
* Two keyword searches
* Five SERP Similarity searches
* Five SERP SERP Analyzer searches
* Five Title AI searches
### How do I sign up for the \$1 trial?
The first step is to head to [www.keywordinsights.ai](http://www.keywordinsights.ai) and sign up for a free account. You can sign up using your email or Google account. Once signed up, you will be asked to setup your workspace.
![Clean Shot 2026 01 29 At 16 54 07@2x]()
Provide the necessary information here and ensure it's accurate.
![Clean Shot 2026 01 29 At 16 55 07@2x]()
Make any changes to your business information.
![Clean Shot 2026 01 29 At 16 55 49@2x]()
You can choose to connect your Google search console or skip this step. (You can connect this later)
![Clean Shot 2026 01 29 At 16 56 28@2x]()
Click - Start Trial.
![Clean Shot 2026 01 29 At 16 57 35@2x]()
In the next screen, click 'Start Trial"
![Clean Shot 2026 01 29 At 16 58 14@2x]()
Read the terms carefully and click Start Trial again.
![Clean Shot 2026 01 29 At 16 58 47@2x]()
Please fill out your credit card details and click Pay. \
\
Note: If you’re signing up as a business, please select the “I’m purchasing as a business” checkbox and provide your business name and tax registration details (VAT). If you don’t do this, we won’t be able to generate a VAT invoice later, as this is not permitted by Stripe.
![Clean Shot 2026 01 29 At 17 00 02@2x]()
You will be redirected back to the app home page. You can the trial status here.
![Clean Shot 2026 01 29 At 17 01 52@2x]()
You can see your credits and all other offerings here.
![Clean Shot 2026 01 29 At 17 02 30@2x]()
### How long does the trial last?
You will have 7 days to test the tool. After this time, all your credits and other offerings will reset, and access to the tool will be restricted.
### What happens after the trial ends?
At the end of the trial you will be **automatically downgraded** to pay as you go version of the tool. You won't be charged anything unless you decide to sign up for one of our subscription plans.
### What can i do with my Trial plan?
Our credits are universal, and with your trial, we’ll provide you with 5000 free credits. These credits will allow you to explore and test every feature within the app. However, some features may have limitations to prevent abuse, such as keyword clustering being limited to 500 keywords.
# Workspaces
Source: https://docs.keywordinsights.ai/utilities/workspaces
### What are Workspaces?
Workspaces are the foundation of Keyword Insights. They allow you to link a domain (also called a workspace or property) to your account so that everything you do in the platform is tied to a specific domain.
By setting up workspaces, you ensure your data, reports, and projects are organized correctly. Workspaces also unlock future features such as reporting, keyword management, performance tracking, and more personalized experiences based on your business context.
### How to Set Up a Workspace
**Step 1 - Add your brand name, domain, target country and language**
When you sign up, new users are prompted to add a bunch of details during onboarding.
![]()
In the first step, you will be asked to provide a few important details. Make sure the information is accurate, as these settings cannot be changed once a workspace is created.
**Brand name:** This is your brand name. e.g: Nike or Universal containers
Please enter your brand name exactly as it is used in your business. This ensures our future features, such as brand mention detection, can accurately recognize and track your brand.
**Workspace domain:** This is your brands domain name. Use one workspace per domain to keep all related projects and reports in one place.
**Location:** Your target country.
**Language:** Your target language.
**Step 2 - Select Your Workspace**
Once you enter the details in step one, we will automatically gather and pre-fill the required data for step two.
![]()
This information is important because it is used to personalize your output and enable future features.
![]()
You will be able to review and edit this information as needed. Please double-check everything before moving on to the final step.
Users can select the "Legacy Platform" workspace and continue to use the tool as it is without the new workspaces feature.
**Step 3 - Connect Google Search Console**
In the final step, you have the option to connect your Google Search Console account. This allows us to link your GSC data with your clusters and other features in the future. While this step is optional, we strongly recommend connecting your account for the best experience. If you prefer, you can skip it now and connect later from the Integrations page.
Important: We [never sell or share](https://www.keywordinsights.ai/privacy-policy/) your Google Search Console data with third parties. Your data is not exposed to any LLM models. If you delete your data, all imported GSC data is permanently deleted as well.
![]()
**Important:** To connect a Google Search Console account to your Workspace, you’ll need full domain-level access verified through DNS records. If you don’t have this, ask your webmaster for access. You can also skip this step for now and complete the connection later.
Once added, you’ll see a global domain selector in the top navigation bar.
![]()
All features you use in Keyword Insights will now pre-populate with the selected domain, language, and location
![]()
### What if I am an existing customer and do not want to use Workspaces?
We have enabled a Legacy Mode for existing customers. You can select this option from the dropdown menu to continue working as usual.
![]()
Please note that Legacy Mode **will not be supported indefinitely**. Once the majority of customers have transitioned to Workspaces, Legacy Mode will be discontinued.
We highly recommend gradually moving your projects into Workspaces to benefit from improved organization and upcoming features such as Brand Echo.
### How many Workspaces can I get?
Workspaces are assigned according to your subscription plan, with each workspace tied to a unique domain.
| Basic | Professional | Premium |
| ----- | ------------ | ------- |
| 5 | 10 | 25 |
### As a Legacy user, are there limits on how many Workspaces I can use?
Yes. To support long-time customers who may have built up many projects, Legacy users are allocated 10 Workspaces. This gives you enough capacity to migrate existing projects at your own pace.
### How do we organize Projects and Folders in Legacy Mode and Workspaces?
Projects and folders are always linked to specific domains within Workspaces. This flexibility ensures your reporting and content planning remain well organized.
### How do I manage Team Visibility?
All team members automatically see all Workspaces within the organization. For more control, you can adjust access at the folder or project level.
### How do Integrations work in Workspaces?
Google Search Console and WordPress integrations are validated and linked directly to Workspaces. Each Google Search Console account can only be added once to prevent duplication.
### How do I delete a Workspace?
To delete a Workspace, go to Manage Workspaces and select Delete. You will be asked to confirm before proceeding. Once confirmed, the Workspace and all related folders and projects will be permanently deleted. This action cannot be reversed.
![]()
If you delete a workspace, **all associated folders and projects will be permanently removed**. You will be asked to confirm before proceeding. Please note that this action cannot be reversed, and Snippet Digital is not responsible for any data loss caused by misuse of this feature.
#### Best Practices for using workspaces
* Use one workspace per domain to keep all related projects and reports in one place.
* Check your subscription plan before adding domains, as limits vary by plan.
* Share strategically by using folder or project-level permissions when needed.
* Review workspaces regularly and clean up unused ones for better efficiency.