Overview

The Semrush SEO API provides backlink, keyword, and domain analytics data. Use it to analyze organic and paid search performance, track rankings, research competitors, and add SEO data to reports, dashboards, applications, or AI workflows.

Jump to Available dataAvailable data

The Version 4 SEO API includes Backlinks, Keyword reports, and Domain Analytics methods.

Data
What you can retrieve
API methods
Backlinks
Backlinks, referring domains and IPs, indexed pages, anchors, Authority Score, competitors, domain comparison, and historical data.

Jump to Keyword reportsKeyword reports

Data
What you can retrieve
API methods
Keyword metrics
Search volume, keyword difficulty, CPC, competitive density, search intent, SERP features, and the 12-month trend for a keyword.
Keyword ideas
Related and broad-match keyword ideas for a seed keyword, with SEO and PPC metrics for each keyword.

Jump to Domain AnalyticsDomain Analytics

Data
What you can retrieve
API methods
Domain overview
Summary metrics and their monthly history for a domain, subdomain, subfolder, or page, and rankings of domains by search metrics.
Organic search
Organic positions and position changes, ranked pages, subdomains, competitors, position trends, and the SERP results for a keyword.
Keyword gap
Keywords that several domains have in common or that only some of them rank for.
Paid search
Paid keywords and their changes, ads, landing pages, competitors, subdomains, keyword coverage, ranking trends, and the ads and advertisers for a keyword.
Google Shopping
Shopping ads of a domain, their positions and competitors, and overview trends.
Databases
Supported country and device type pairs.

Jump to Get accessGet access

You need access to the SEO API and a Version 4 API key, which is assigned to each user after subscribing to Semrush. For help setting up API access, refer to API access.

Requests use API units. For the price of a method, refer to its reference.

Jump to AuthorizationAuthorization

You’ll find your API key in the API keys section of your Semrush profile.

Include your API key in the Authorization header of every request:

Monthly domain summaries request
Shell
curl -H 'Authorization: Apikey YOUR_API_KEY' \
  'https://api.semrush.com/apis/v4/domain-analytics/v1/domain-summaries/monthly?url=example.com&scope=ROOT_DOMAIN&country=US&device_type=DESKTOP'

Jump to Response formatResponse format

All SEO API methods return JSON by default. Backlinks and Keyword reports methods also return CSV: set format=csv where the method supports the format parameter.

Successful JSON responses contain:

  • meta: Request details, including request_id, status_code, and success.
  • data: Results. List methods return an array, and summary methods return an object.

The method reference lists the response fields and includes response examples.

Jump to Request parametersRequest parameters

The parameters depend on the method:

  • Target: Most methods use url and scope. scope supports ROOT_DOMAIN, SUBDOMAIN, SUBFOLDER, and PAGE, though some methods support fewer values. Competitor and subdomain methods use domain, and keyword methods use keyword. Comparison methods take several targets, for example, urls or target_url and competitor_url.
  • Database: Domain Analytics and Keyword reports methods use country. Domain Analytics methods also use device_type. To check which country and device_type pairs are supported, use Get Supported Countries.
  • Time period: Monthly methods use month in the YYYY-MM format. Trend and history methods use date_from and date_to, and organic search change methods use base_month and comparison_month, in the same format.
  • Fields, sorting, and pagination: Where supported, use fields to select response fields, order_by and direction to sort results, and limit and offset to page through them. For field names, refer to Columns.
  • Filtering: Many methods support the filter parameter. The syntax is shared, but the available fields, operators, and value formats depend on the section and method. For the syntax and the differences between sections, refer to Advanced filtering.

Jump to Advanced filteringAdvanced filtering

Most API endpoints provide standard query parameters for filtering and sorting results.

Use the filter parameter when standard parameters are insufficient, for example, when you need comparison operators such as >, pattern matching such as LIKE, or logical disjunction such as OR.

The filter syntax is the same in all sections, but the available fields, operators, and value formats depend on the section and method. For example, cpc is in USD cents in Keyword reports and in USD in Domain Analytics. For the fields you can filter by, refer to the filter parameter in the method reference.

Jump to SyntaxSyntax

The filter parameter uses the following format: Field Operator Value. Combine conditions with AND and OR, and use parentheses for grouping.

Section
Example
Backlinks
source_url LIKE "https://blog.%" AND page_score > 50
Keyword reports
search_volume > 100 AND keyword_difficulty <= 49
Domain Analytics
volume > 1000 AND keyword CONTAINS "buy"

Jump to Supported operatorsSupported operators

Section
Operators
Backlinks
Comparison operators, LIKE, and NOT LIKE. With LIKE and NOT LIKE, use % as a wildcard.
Keyword reports
Numeric fields: =, !=, >, >=, <, <=. The keyword field: =, !=, CONTAINS, WORD_MATCH. The intents and serp_features arrays: HAS.
Domain Analytics
Comparison operators =, !=, >, >=, <, <=. CONTAINS for text fields. STARTS_WITH, ENDS_WITH, and IN in Monthly Ranked Pages. HAS_ANY for SERP feature fields.

Jump to Data typesData types

  • Strings: Wrap in double quotes. Backlinks methods also accept single quotes.
  • Numbers: Keyword reports accept non-negative integers, and cpc is in USD cents. Domain Analytics accepts integers and decimals, and cpc is in USD, filtered by its numeric value without the currency, for example, cpc > 2.50.
  • Booleans: true or false, case-insensitive.
  • Lists or arrays: Use parentheses and separate items with commas, for example, keyword_serp_features HAS_ANY ("REVIEWS", "AI_OVERVIEW").

Jump to ColumnsColumns

These columns apply to Backlinks and Keyword reports methods. Domain Analytics field names, such as volume, competition_density, and results, are listed in each method’s reference. In Domain Analytics, cpc is in USD.

For v4 methods that support the fields query parameter, you can use these field names to include only the data relevant to your analysis. Keyword reports methods have no fields parameter. In List Related and List Broad Match, you can use these names in filter and order_by.

Field
Description
API methods
anchor
Backlink anchor text.
backlinks_counts
Number of backlinks from the domain to each requested target, in the same order as the targets in the request.
common_refdomains
Number of referring domains shared with the target domain.
competitive_density
Competition level of advertisers bidding on the analyzed keyword within their PPC campaigns.
cpc
Average price, in USD cents, that advertisers pay for a click on an ad triggered by the analyzed keyword.
domain_score
Source domain authority score.
external_links_count
Number of external links found on the source page.
first_seen_at
Date and time when the item was first found.
follows_count
Number of follow backlinks.
forms_count
Number of backlinks placed in forms.
frames_count
Number of backlinks placed in iframes.
image_alt
Value of the image alt attribute if the backlink is an image.
image_url
Value of the image src attribute if the backlink is an image.
images_count
Number of image backlinks.
intents
Search intents associated with the keyword.
internal_links_count
Number of internal links found on the source page.
ip_address
Source page IP address.
ip_class_c_count
Number of referring IP class C subnets.
ips_count
Number of referring IP addresses.
is_follow
Whether the referring domain is dofollow.
is_form
Whether the backlink is inside a form element.
is_frame
Whether the backlink is inside an iframe.
is_image
Whether the backlink is image-based.
is_lost
Whether the backlink is lost.
is_new
Whether the backlink is new.
is_nofollow
Whether the backlink has the rel="nofollow" attribute.
is_sitewide_main
Whether this backlink is the main URL among sitewide backlinks.
is_sponsored
Whether the backlink has the rel="sponsored" attribute.
is_ugc
Whether the backlink has the rel="ugc" attribute.
keyword
Keyword idea returned for the seed keyword.
keyword_difficulty
Measure of how difficult it is to rank organically in Google’s top 10 results for the analyzed keyword.
lang
Language of the source page.
last_seen_at
Date and time when the item was last seen.
lost_count
Number of lost backlinks.
matches_count
Number of analyzed targets this domain refers to.
month_date
Start of the month.
new_count
Number of new backlinks.
nofollows_count
Number of nofollow backlinks.
number_of_results
Number of URLs displayed in organic search results for the keyword.
page_score
Source page authority score.
redirect_url
Original URL when the source page URL redirects.
relevance
How closely the keyword relates to the seed keyword, on a scale from 0 to 100.
response_code
HTTP status code of the source page.
score
Page score for URL scope; domain score for all other scopes.
search_volume
Average number of monthly searches for the keyword over the past 12 months.
serp_features
SERP features triggered by the keyword.
similarity
Similarity to the target domain.
source_domain
Source page domain.
source_size
Source page content size in bytes.
source_title
Title of the source page where the backlink was found.
source_url
Source page URL.
sponsored_count
Number of sponsored backlinks.
target_title
Value of the title attribute on the source page’s anchor element.
target_url
Target page URL.
texts_count
Number of text backlinks.
trends
Monthly search interest over the last 12 months.
ugc_count
Number of UGC backlinks.
url
Target URL as it was passed in the request.
urls_count
Number of referring pages.

Jump to Error handlingError handling

When a request fails, the API returns a structured error response. Check the HTTP status and the error object. If the response includes error.retryable, don’t retry requests marked false.

Error response example
JSON
{
  "meta": {
    "success": false,
    "status_code": 403,
    "request_id": "a29952029c10a47e5876d86256e59455"
  },
  "error": {
    "code": 403,
    "message": "Forbidden",
    "retryable": false,
    "details": {}
  }
}

Jump to Response fieldsResponse fields

Field
Description
meta.success
Indicates whether the request was successful.
meta.status_code
HTTP status code returned by the API.
meta.request_id
Unique request identifier that can be used when contacting support.
error.code
Error code. Usually matches the HTTP status code.
error.message
Error description.
error.retryable
Indicates whether retrying the request may succeed.
error.details
Additional error information. The structure depends on the specific error and endpoint.

Jump to HTTP status codesHTTP status codes

HTTP code
Description
400 Bad Request
The request contains invalid parameters or cannot be processed.
401 Unauthorized
Authentication failed or credentials are missing.
403 Forbidden
The authenticated user does not have permission to perform the operation.
404 Not Found
User information wasn’t found in the Semrush database.
409 Conflict
The request conflicts with the current state of the resource.
429 Too Many Requests
The request rate is too high.
499 Client Closed Request
The client closed the connection before the request completed.
500 Internal Server Error
An unexpected server error occurred.
501 Not Implemented
The requested operation is not implemented.
503 Service Unavailable
The service is temporarily unavailable.
504 Gateway Timeout
The request timed out while waiting for a backend service.

When contacting Support, include the request, response, and meta.request_id. For more help, refer to Troubleshooting.

Jump to FAQFAQ

Jump to What data can I retrieve with the SEO API?What data can I retrieve with the SEO API?

The Version 4 SEO API provides backlink, keyword, and domain analytics data through the Backlinks, Keyword reports, and Domain Analytics methods. For an overview by data type, refer to Available data.

Jump to What can I build with the SEO API?What can I build with the SEO API?

You can build SEO dashboards, reporting tools, internal applications, AI-powered workflows, and custom integrations using Semrush SEO data. To make your first request, refer to the Quick start guide.

Jump to Why should I use Version 4 Semrush API?Why should I use Version 4 Semrush API?

Version 4 Semrush API is the recommended version for new integrations. It uses modern authorization and provides JSON responses. To compare what each version covers, refer to API versions.

Last updated: November 13, 2026

Was this page helpful?