Serpstat Integration with SmythOS

Want to build a powerful, automated SEO research engine? Connect Serpstat to SmythOS and empower your agents to perform in-depth keyword research, competitor analysis, and backlink audits automatically.

TL;DR

Securely link your Serpstat account to SmythOS using an API token. Then, use our extensive suite of components to automate every aspect of your SEO and digital marketing research, from finding related keywords to analyzing competitor ad copy.

List of Serpstat Components

Quickly compare Serpstat components by what they do and their key I/O. This is a comprehensive suite for all your SEO data needs.

Component	Action	What it Does	Inputs	Key Outputs	Use Case
Keyword Research	Research	Gathers organic keywords related to a seed keyword.	keyword, se	result_data	Finding long-tail variations of a target keyword.
Related Keywords	Research	Retrieves related keywords with their metrics.	search_question	keyword, volume	Building a topic cluster for content strategy.
Search Suggestions	Research	Provides search suggestions for a given keyword.	keyword, se	result_data	Understanding user search behavior and intent.
Domain Keywords	Research	Finds keywords a specific domain ranks for.	domain, se	result_data	Analyzing a competitor's organic keyword strategy.
Missing Keywords	Research	Finds keywords competitors rank for, but your URL doesn't.	url, se	result_data	Identifying content gaps and SEO opportunities.
Competitors in OSERP	Research	Lists a domain's main competitors in organic search.	domain, se	result_data	Identifying who you're up against in the SERPs.
Domain Ads	Research	Returns paid keywords and ad copy for a domain.	domain, se	result_data	Analyzing a competitor's PPC strategy and ad copy.
Active Backlinks	Audit	Retrieves a list of active backlinks pointing to a domain.	query, searchType	result_data	Monitoring your link-building efforts.
Referring Domains	Audit	Lists all unique domains linking to the analyzed site.	query, searchType	result_data	Assessing the quality of a site's link profile.
Top Pages (Backlink)	Audit	Lists the pages on a site with the most backlinks.	query, searchType	result_data	Identifying your most authoritative content.
Summary Report	Report	Gets general information about a domain's link profile.	query, searchType	result_data	A quick overview of a domain's backlink health.
Create Serpstat Project	Write	Creates a new project in your Serpstat account.	domain, name	project_id	Setting up a new client or website for tracking.
List Serpstat Projects	Read	Retrieves a list of all your projects in Serpstat.	id	result_data	Finding a project_id for other operations.
Audit Start	Write	Initiates a site audit for a specified project.	projectId	reportId	Kicking off a technical SEO audit automatically.
List Audits	Read	Provides a list of all site audits for a project.	projectId	result	Checking the history of site audits.
Add User To Team	Write	Invites a new user to join your Serpstat team.	email	success, user_id	Automating user provisioning for new team members.

(This is a selection of the most common components. A full, detailed list follows in the Component Details sections.)

INFO

Why Integrate Serpstat with Your Agent?

Serpstat is a comprehensive SEO toolkit. Integrating it with SmythOS allows you to build powerful agents that can automate nearly every aspect of SEO research, analysis, and reporting.

• Automate Competitor Analysis: Create agents that run weekly to track your competitors' ranking keywords, new backlinks, and top pages, delivering a competitive intelligence report directly to you.
• Streamline Keyword Research: Build a workflow that takes a single "seed" keyword, uses Related Keywords and Search Suggestions to build a massive list of potential targets, and then filters that list based on volume and competition.
• Automated Content Audits: Use agents to find content gaps by comparing your domain's keywords to your competitors' with the Missing Keywords component, providing a ready-made list of content to create.
• Automate SEO Reporting: Schedule agents to fetch data from Domain History, Backlinks Dynamics, and URL Rank Keywords to build custom, automated reports on your site's SEO performance over time.

Prerequisites

Before you begin, please ensure you have the following:

• An active SmythOS account. (Sign up here).
• A Serpstat account with an active subscription that includes API access.
• Your Serpstat API Token.

Getting Started With Serpstat

The connection between SmythOS and Serpstat is configured using a secure API Token.

Step 1: Get Your Serpstat API Token

1. Log in to your Serpstat account.
2. Navigate to your Profile Settings.
3. Find the API section.
4. Your API Token will be displayed here. If it's not present, you may need to generate it.
5. Copy the token to your clipboard.

Step 2: Store Your API Token in SmythOS Vault

Your API Token is a sensitive credential. Use the SmythOS Vault to store it securely.

1. In your SmythOS dashboard, navigate to the Vault.
2. Create a new secret and paste your Serpstat API Token as the value. Give it a memorable name, like serpstat_api_token.
3. For more details, see the Vault Documentation.

Step 3: Configure a Serpstat Component

1. In your SmythOS agent graph, drag and drop any Serpstat component.
2. Click the component to open its Settings panel.
3. In the API Token field, select the secret you saved in the Vault (e.g., serpstat_api_token).
4. Your connection is now configured for that component.

Heads-up

You must add the API Token from the Vault to each Serpstat component you use. This ensures all your API calls are properly authenticated.

Which Serpstat Component Should I Use?

If you need to…	Target	Use this Component	Why this one?
Find new keyword ideas for a blog post	A seed keyword	Related Keywords	Expands your topic into a list of semantically similar keywords with metrics.
See what your competitor ranks for	A competitor's domain	Domain Keywords	The best way to analyze a competitor's entire organic keyword footprint.
Find easy content opportunities	Your domain and a competitor's	Missing Keywords	Directly shows you what keywords your competitors rank for that you don't.
Check your backlink profile health	Your domain	Active Backlinks	Provides a full list of all current backlinks pointing to your site.
Start a technical SEO audit for a new client	A projectId	Audit Start	Kicks off Serpstat's comprehensive site audit tool programmatically.
Get a quick overview of a domain's stats	A domain	Summary Report	Provides a high-level snapshot of a domain's visibility, traffic, and keywords.

Component Details

This section provides detailed information for each Serpstat component.

Search Suggestions

Provides search suggestions for the keyword you requested through full-text search functionality.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
keyword	string	Yes	The search term to analyze.
se	string	Optional	Search engine and region (e.g., g_us). Default: g_us.
page	integer	Optional	Page number for pagination. Default: 1.
size	integer	Optional	Number of results per page. Default: 100.

Outputs

Field	Type	Description
result_data	array	An array containing search suggestion results.
total	integer	Total number of available results.
left_lines	integer	Your remaining API requests for the day.

Use Case

An agent takes a broad topic like "content marketing" and uses this component to discover what specific long-tail searches users are performing related to it.

{
  "component": "serpstat.searchSuggestions",
  "id": "req-123",
  "keyword": "how to build ai agents",
  "se": "g_uk"
}

Keywords Selection

Exports organic keywords associated with the researched keyword to a CSV file.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
keyword	string	Yes	The keyword to analyze.
se	string	Optional	Search engine and region. Default: g_us.

Outputs

Field	Type	Description
Response	object	The API response, which will contain information about the export task.

Use Case

To perform a deep analysis, an agent uses this component to export thousands of organic keywords related to a core term into a CSV for processing in another tool.

Related Keywords

Retrieves related keywords with their metrics and search intent data.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
search_question	string	Yes	The keyword to find related terms for.
search_country	string	Yes	Target country for search data.

Outputs

Field	Type	Description
keyword	string	The related keyword found.
volume	integer	The search volume for the related keyword.
cpc	float	The Cost Per Click for the related keyword.
search-intent	string	User intent classification (e.g., informational).
competition_value	float	The level of advertiser competition.

Use Case

A content strategy agent uses this component to find a list of related keywords, then filters them by high volume and low competition_value to identify easy-win topics.

Domain Ads

Returns paid keywords and ad copies for a specific domain.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
domain	string	Yes	The target domain to analyze.
se	string	Yes	Search engine and region. Default: g_us.

Outputs

Field	Type	Description
result_data	array	An array containing the domain's ad data, including keywords and ad copy.
left_lines	integer	Your remaining API requests.

Use Case

A competitive intelligence agent runs this component on a competitor's domain to analyze their PPC strategy, including the keywords they are bidding on and the ad copy they are using.

Ads Examples

Retrieves paid keywords and ad copy examples for specific keywords.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
keyword	string	Yes	The keyword to analyze for ad examples.
se	string	Yes	Search engine and region.

Outputs

Field	Type	Description
result_data	array	An array of ad examples for the specified keyword.
total	integer	The total number of ad examples found.

Use Case

A PPC manager agent uses this component to research ad copy ideas for a new campaign by looking at what top competitors are using for a specific keyword.

Top Pages By Domain

Returns a hierarchical list of a website's pages based on their SEO strength.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
domain	string	Yes	The target domain.
se	string	Optional	Search engine and region. Default: g_us.

Outputs

Field	Type	Description
result_data	array	An array of page objects, ordered by SEO value.
total	integer	The total number of pages found.

Use Case

An SEO agent runs this component on a competitor's site to identify their most powerful pages, which are likely driving the most organic traffic.

URL Rank Keywords

Returns keywords that a specific URL ranks for in the top 100 Google search results.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
url	string	Yes	The target URL to analyze.
se	string	Yes	Search engine and region. Default: g_us.

Outputs

Field	Type	Description
result_data	array	An array of keywords the URL ranks for, including position.
total	integer	Total number of ranking keywords found.

Use Case

An agent analyzes a competitor's top blog post by passing its URL to this component to see all the keywords it ranks for, revealing content optimization strategies.

URL Competitors

Returns a list of URLs that are competitors to a specific URL in organic search.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
url	string	Yes	The target URL to analyze.
se	string	Yes	Search engine and region. Default: g_us.

Outputs

Field	Type	Description
result_data	array	An array of competitor URL objects.
total	integer	Total number of competitors found.

Use Case

To understand the competitive landscape for a specific blog post, an agent uses this component to find the top-ranking competing articles.

Missing Keywords

Returns keywords that competitors rank for but the given URL does not.

INFO

This component requires an API Token for authentication.

Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
url	string	Yes	The URL of your page to analyze.
se	string	Yes	Search engine and region. Default: g_us.

Outputs

Field	Type	Description
result_data	array	An array of keyword objects you are missing.

Use Case

A content optimization agent uses this component to find content gaps by comparing your page to a top competitor, generating a list of keywords to add to your article.

Backlinks & Domains

This group includes components for analyzing a domain's backlink profile, such as Summary Report, Backlinks Dynamics, Referring Domains, Active Backlinks, Lost Backlinks, and more.

INFO

These components require an API Token for authentication.

Common Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
query	string	Yes	The domain or URL to analyze.
searchType	string	Yes	The type of query (e.g., domain, url).

Common Outputs

Field	Type	Description
result_data	object/array	The specific backlink or domain data requested.
left_lines	integer	Your remaining API requests.

Use Case: Backlink Monitoring

A link-building agent runs weekly. It uses Active Backlinks to find new links, checks their quality using Referring Domains to get the domain rating, and sends a report of all new, high-quality links to a Slack channel.

Site Audit

This group includes components for managing technical SEO audits, such as List Audits, Get Project Settings, Audit Start, Stop Running Audit, and analyzing results with components like Audit Basic Info and List Report Issues.

INFO

These components require an API Token for authentication.

Common Inputs

Field	Type	Required	Notes
id	string	Yes	A unique identifier for your request.
projectId	string	Yes	The ID of the project in Serpstat to audit.
reportId	string	Varies	The ID of a specific audit report to analyze.

Common Outputs

Field	Type	Description
reportId	string	(Audit Start) The ID of the new audit report.
progress	integer	(Audit Basic Info) The completion progress of the audit.
result_categories	array	(List Report Issues) A list of issue categories found.

Use Case: Automated Audits

1. An agent uses Create Serpstat Project for a new client's website.
2. It then calls Audit Start to kick off the initial technical SEO audit.
3. Another agent runs daily, uses List Audits to find the latest report, checks the progress, and once complete, uses List Report Issues to send a summary of critical errors to the development team.

Best Practices & Advanced Tips

• Secure Your API Token: Always store your Serpstat API Token in the SmythOS Vault.
• Manage API Lines: Serpstat's API usage is measured in "lines" or requests per day. The left_lines output is crucial for monitoring your consumption. Design agents to be efficient to stay within your plan's limits.
• Use the se Parameter: For accurate, localized data, always specify the search engine and region code (e.g., g_uk for Google UK, g_ca for Google Canada) in your requests.
• Chain Components for Deep Insights: The most powerful workflows combine components. For example, use Domain Keywords to find a competitor's top keyword, then use URL Rank Keywords to see which of their pages ranks for it, and finally use Active Backlinks on that URL to understand why it ranks well.

Troubleshooting Common Issues

• Error: 401 Unauthorized

  • Cause: The API Token is incorrect, invalid, or your Serpstat plan does not include API access.
  • Solution: Verify that the API Token in your SmythOS Vault is correct. Log in to your Serpstat account to confirm your subscription level and that the token is active.

• Error: "You have reached the end of your line limit"

  • Cause: You have exhausted your daily API request quota.
  • Solution: Check the left_lines output on previous successful calls. You must wait for your quota to reset (typically every 24 hours). Consider upgrading your plan for higher limits.

• Empty result_data

  • Cause: The query may genuinely have no data (e.g., a new domain with no keywords), or the se (search engine region) specified has no database for that query.
  • Solution: Double-check your inputs (domain, keyword, se). Test the same query in the Serpstat web application to see if data exists there.

What's Next?

You are now ready to build powerful SEO intelligence workflows with the SmythOS Serpstat Integration!

Consider these ideas:

• Build an Agent That...

  • Creates a "Content Gap Analysis" report. It takes your domain and three competitor domains, uses Domain Keywords on all of them, and then identifies keywords that all three competitors rank for but you do not.
  • Automates outreach prospecting. The agent gets a list of top-ranking articles for a keyword using the URL Rank Keywords component, then finds their contact information using other tools.
  • Monitors for negative SEO. It runs the Lost Backlinks and Malicious Domains Donors components weekly and sends an alert if a significant number of valuable links are lost or new toxic links are found.

• Explore Other Integrations:

  • Combine Serpstat with an LLM component. Use Related Keywords to get a list of topics, then have the LLM write a draft article for the most promising one.
  • Feed the output of your Serpstat reports directly into a Google Sheet to create custom SEO dashboards and track performance over time.
  • When your agent discovers a new, high-authority backlink, post a celebratory message to a Slack or Microsoft Teams channel.