Migrate SEO API from v3 to v4

This guide provides step-by-step instructions for migrating your existing Semrush SEO API integrations from v3 to v4.

It covers changes to API endpoints, request parameters, and response formats, with practical migration examples for Backlinks, Keyword reports, and Domain Analytics methods.

The guide focuses on commonly used methods and operations with significant changes between v3 and v4.

Jump to Before you startBefore you start

Before migrating your integration:

1. List the v3 methods your application uses.
2. Prepare a test environment where you can compare v3 and v4 results.

Jump to Step 1. Get v4 API keyStep 1. Get v4 API key

API v3 and v4 use version-specific API keys. You need a v4 API key to authenticate requests to v4 endpoints.

1. Create a v4 API key.
2. Configure the required permissions and optionally set an expiration date for added security.
3. Store the API key securely.
4. Update your integration to use the new key.

Pass your API key in the Authorization header:

Authorization: Apikey YOUR_API_KEY

For more information, refer to API v4 authorization.

Jump to Step 2. Find corresponding v4 endpointsStep 2. Find corresponding v4 endpoints

To identify the correct replacement:

1. Find the v3 method in the v3 and v4 comparison reference.
2. Identify the equivalent v4 endpoint or endpoints, including any changes to API groups.
3. Check if reproducing the same result requires multiple v4 requests.

For example, v3 Backlinks Overview (type=backlinks_overview) is replaced by the v4 /apis/v4/backlinks/v1/overview endpoint. For a full walkthrough, refer to Example 1.

Similarly, the v3 Domain, Overview, Subdomain, Subfolder, and URL reports are replaced by Domain Analytics endpoints. For example, v3 Domain Organic Search Keywords (type=domain_organic) is replaced by Monthly Organic Positions. For a full walkthrough, refer to Example 4.

If a method is not yet supported in v4, check its status in the comparison reference.

Jump to Step 3. Update your API requestsStep 3. Update your API requests

After identifying the corresponding v4 endpoints, update your request URLs, parameters, and response handling.

Jump to Update endpoint URLsUpdate endpoint URLs

Replace the v3 endpoint and type parameter with the corresponding v4 endpoint URL from the method mapping.

Jump to Update request parametersUpdate request parameters

To make parameter names more intuitive and self-explanatory, some parameters have been renamed, reorganized, or replaced in v4. For example, target becomes url, database becomes country, and date parameters use new formats.

Review the request parameter differences for each method before updating your integration.

Jump to Update response handlingUpdate response handling

Response formats and field names may differ between v3 and v4. For example, *_num count fields become *_count, and some metrics use different units.

In v4, JSON is the default response format, and JSON responses separate metadata in meta from results in data.

If your integration parses API responses, update the relevant code to handle the new field names and response structure. If your integration uses CSV, check whether the v4 endpoint supports the required format and update your parser accordingly.

For a complete list of changes, refer to Response parameter differences.

For step-by-step examples of these changes, refer to Migration examples.

Jump to Step 4. Test your updated integrationStep 4. Test your updated integration

Before switching production requests to v4, test your updated integration.

1. Confirm that your v4 API key has the necessary permissions.
2. Check that your application can call the v4 endpoints.
3. Make sure your application correctly processes v4 responses.
4. Confirm that v4 returns the data your use cases require.
5. Verify that multi-request workflows retrieve and process all required data.
6. Check API Unit consumption and limits, especially for multi-request workflows.
7. Make sure your integration handles v4 errors correctly.

When comparing results, pay particular attention to changes in field names, data types, metric units, date formats, and data availability.

Jump to Step 5. Switch to v4Step 5. Switch to v4

Once your updated integration has been tested:

1. Switch the verified operations from v3 to v4.
2. Monitor the integration for errors and unexpected results.
3. Check API Unit consumption.
4. Continue migrating any remaining supported v3 methods.
5. Remove unused v3-specific configuration after completing the migration.

Jump to Migration examplesMigration examples

The following examples demonstrate how to migrate commonly used SEO API methods from v3 to v4.

They cover different migration scenarios:

• Replacing an endpoint and updating request parameters.
• Updating response fields and metric formats.
• Replacing a single v3 request with multiple v4 requests.

For other methods, refer to the Semrush API v3 and v4 comparison reference.

Jump to Example 1. Migrate Backlinks OverviewExample 1. Migrate Backlinks Overview

Use this example if your integration retrieves backlink statistics for a domain, subdomain, or URL.

In v3, Backlinks Overview uses the shared analytics endpoint:

GET /analytics/v1/?type=backlinks_overview

In v4, use the dedicated Backlinks Overview endpoint:

GET /apis/v4/backlinks/v1/overview

What you need to change:

1. Replace the v3 endpoint with the v4 Overview endpoint.
2. Replace target with url.
3. Replace target_type with scope.
4. Pass your v4 API key in the Authorization header.
5. Update your response parser to use the new field names:
   • If your application reads the authority score from ascore, update it to read score.
   • If your application reads the total number of backlinks from total, update it to read backlinks_count.

Check the response format. JSON is the default format in v4, and the response separates metadata from results.

Sample requests and responses:

curl "https://api.semrush.com/analytics/v1/?key=YOUR_API_KEY&type=backlinks_overview&target=searchenginejournal.com&target_type=root_domain&export_columns=ascore,total,domains_num,urls_num,ips_num,ipclassc_num,follows_num,nofollows_num,sponsored_num,ugc_num,texts_num,images_num,forms_num,frames_num"

ascore;total;domains_num;urls_num;ips_num;ipclassc_num;follows_num;nofollows_num;sponsored_num;ugc_num;texts_num;images_num;forms_num;frames_num
74;22063983;49145;13059030;47793;22956;20457307;1606307;258;1475;21784602;278624;437;320

curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/backlinks/v1/overview?url=example.com&scope=ROOT_DOMAIN"

{
    "meta": {
        "request_id": "4fb1773ec2a8d61a0407f464599f897c",
        "status_code": 200,
        "success": true
    },
    "data": {
        "backlinks_count": 2341,
        "domains_count": 156,
        "follows_count": 1823,
        "forms_count": 12,
        "frames_count": 8,
        "images_count": 42,
        "ip_class_c_count": 89,
        "ips_count": 142,
        "lost_count": 15,
        "new_count": 23,
        "nofollows_count": 518,
        "score": 78,
        "sponsored_count": 45,
        "texts_count": 1987,
        "ugc_count": 234,
        "urls_count": 267
    }
}

In this example, target_type=root_domain becomes scope=ROOT_DOMAIN. v4 returns all fields by default, so you don’t need export_columns. To return selected fields only, use fields. v4 also returns new_count and lost_count, which aren’t available in this v3 report.

Jump to Example 2. Migrate Keyword OverviewExample 2. Migrate Keyword Overview

Use this example if your integration retrieves search volume, CPC, keyword difficulty, and other metrics for a keyword.

In v3, Keyword Overview for One Database uses the phrase_this report:

GET /?type=phrase_this

In v4, use the Keyword Metrics endpoint:

GET /apis/v4/keywords/v1/metrics

Jump to 1. Update request parameters1. Update request parameters

For example, a display_date value of 20260215 becomes 2026-02. The month parameter is optional and defaults to the current month.

Jump to 2. Update response fields2. Update response fields

v4 also returns serp_features, which has no v3 equivalent in this report.

Jump to 3. Update metric processing3. Update metric processing

Some metrics use different formats or units:

For example, a competitive density value of 0.75 in v3 corresponds to 75 in v4.

If your application displays CPC in dollars, convert the v4 value from cents. If your application processes search intent, update it to handle string values instead of numeric codes.

Sample requests and responses:

curl "https://api.semrush.com/?type=phrase_this&key=YOUR_API_KEY&phrase=seo&export_columns=Ph,Nq,Cp,Co,Nr,Td&database=us"

Keyword;Search Volume;CPC;Competition;Number of Results;Trends
seo;110000;14.82;0.5;678000000;0.81,1.00,1.00,1.00,1.00,0.81,0.81,0.81,0.81,0.81,0.81,0.81

curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/metrics?keyword=seo%20tools&country=US&month=2024-01"

{
    "meta": {
        "country": "US",
        "keyword": "seo tools",
        "month": "2024-01",
        "request_id": "4fb1773ec2a8d61a0407f464599f897c",
        "status_code": 200,
        "success": true
    },
    "data": {
        "competitive_density": 78,
        "cpc": 1245,
        "intents": ["COMMERCIAL", "INFORMATIONAL"],
        "keyword_difficulty": 74,
        "number_of_results": 1850000000,
        "search_volume": 60500,
        "serp_features": ["SITELINKS", "PEOPLE_ALSO_ASK", "AI_OVERVIEW", "RELATED_SEARCHES"],
        "trends": [82, 78, 85, 90, 88, 92, 95, 100, 96, 91, 87, 84]
    }
}

In the v4 response, cpc of 1245 means $12.45, and competitive_density of 78 corresponds to 0.78 in v3. The keyword, country, and month are in meta, not in data.

Jump to Example 3. Migrate Keyword Overview for All DatabasesExample 3. Migrate Keyword Overview for All Databases

Some migrations require changing the request workflow rather than simply replacing an endpoint.

For example, the v3 Keyword Overview for All Databases report retrieves keyword metrics across multiple databases.

In v3, use the phrase_all report:

GET /?type=phrase_all

This report retrieves keyword metrics across multiple databases in a single request.

In v4, use the Keyword Metrics endpoint:

GET /apis/v4/keywords/v1/metrics

The v4 endpoint accepts one keyword and one country per request.

What you need to change to reproduce a multi-country report:

1. Identify the countries required by your integration.
2. Send a separate Keyword Metrics request for each country.
3. Collect the responses.
4. Combine the results in your application if a consolidated report is required.

Each v4 request consumes API units, so reproducing one phrase_all request for N countries costs N Keyword Metrics requests. Review API Unit consumption and applicable limits before migrating this workflow.

In v3, one request returns metrics for the keyword in every database.

curl "https://api.semrush.com/?type=phrase_all&key=YOUR_API_KEY&phrase=seo&export_columns=Dt,Db,Ph,Nq,Cp,Co,Nr"

Date;Database;Keyword;Search Volume;CPC;Competition
201903;bo;seo;390;0.44;0.03
201903;hu;seo;1900;0.82;0.45
201903;th;seo;5400;0.96;0.49
201903;cr;seo;590;0.43;0.14

In v4, send one request per country. For example, to get metrics for the United States, United Kingdom, and Germany:

curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/metrics?keyword=seo&country=US"
curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/metrics?keyword=seo&country=UK"
curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/metrics?keyword=seo&country=DE"

Each response has the same structure as in Example 2. Use meta.country to identify the country of each response. Note that v3 database codes are lowercase, such as us, while v4 country codes are uppercase, such as US.

Jump to Example 4. Migrate Domain Organic Search KeywordsExample 4. Migrate Domain Organic Search Keywords

Use this example if your integration retrieves the keywords a domain ranks for in Google’s organic search results.

In v3, Domain Organic Search Keywords uses the domain_organic report:

GET /?type=domain_organic

In v4, use the Monthly Organic Positions endpoint:

GET /apis/v4/domain-analytics/v1/organic-search/keywords/monthly

The same endpoint works for subdomains, subfolders, and URLs, so it also replaces the subdomain_organic, subfolder_organic, and url_organic reports.

Jump to 1. Update request parameters1. Update request parameters

For example, the v3 filter +|Ph|Co|seo (keywords that contain seo) becomes keyword CONTAINS "seo" in v4.

Some v3 options aren’t available in this endpoint:

• display_daily: v4 returns monthly data only.
• display_positions: to get new, lost, improved, or declined positions, use the Monthly Position Changes endpoint with change_types, base_month, and comparison_month.

Jump to 2. Update response fields2. Update response fields

traffic_percent and traffic_cost_percent are shares of the domain’s total traffic and traffic cost, while traffic is an estimated number of visits.

Jump to 3. Update metric processing3. Update metric processing

Some metrics use different formats or units:

For example, a v3 CPC of 14.82 becomes "cpc": {"value": 14.82, "currency": "USD"} in v4, and a competition value of 0.50 becomes 50.

Sample requests and responses:

curl "https://api.semrush.com/?type=domain_organic&key=YOUR_API_KEY&domain=seobook.com&database=us&display_limit=10&display_sort=tr_desc&display_filter=%2B%7CPh%7CCo%7Cseo&export_columns=Ph,Po,Pp,Pd,Nq,Cp,Ur,Tr,Tc,Co,Nr,Td"

Keyword;Position;Previous Position;Position Difference;Search Volume;CPC;Url;Traffic (%);Traffic Cost (%);Competition;Number of Results;Trends
seo;9;10;1;110000;14.82;http://www.seobook.com/;17.53;44.40;0.50;0;0.81,1.00,1.00,1.00,1.00,0.81,0.81,0.81,0.81,0.81,0.81,0.81
seobook;1;1;0;1300;4.54;http://www.seobook.com/;5.52;4.28;0.32;379000;0.62,0.81,0.62,0.81,0.81,0.62,0.62,0.81,0.81,0.62,1.00,0.81

curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/domain-analytics/v1/organic-search/keywords/monthly?url=seobook.com&scope=ROOT_DOMAIN&country=US&device_type=DESKTOP&position_type=ORGANIC&limit=10&order_by=traffic_percent&direction=DESC&filter=keyword%20CONTAINS%20%22seo%22&fields=keyword,position,position_previous,position_difference,volume,cpc,url,traffic_percent,traffic_cost_percent,competition_density,results,trends"

{
    "meta": {
        "request_id": "4fb1773ec2a8d61a0407f464599f897c",
        "status_code": 200,
        "success": true,
        "url": "seobook.com",
        "effective_url": "https://seobook.com",
        "scope": "ROOT_DOMAIN",
        "country": "US",
        "device_type": "DESKTOP",
        "month": "2026-10",
        "position_type": "ORGANIC",
        "filter": "keyword CONTAINS \"seo\"",
        "limit": 10,
        "offset": 0
    },
    "data": [
        {
            "keyword": "seo",
            "position": 9,
            "position_previous": 10,
            "position_difference": 1,
            "volume": 110000,
            "cpc": {
                "value": 14.82,
                "currency": "USD"
            },
            "url": "http://www.seobook.com/",
            "traffic_percent": 17.53,
            "traffic_cost_percent": 44.4,
            "competition_density": 50,
            "results": 0,
            "trends": [81, 100, 100, 100, 100, 81, 81, 81, 81, 81, 81, 81],
            "type": "ORGANIC"
        },
        {
            "keyword": "seobook",
            "position": 1,
            "position_previous": 1,
            "position_difference": 0,
            "volume": 1300,
            "cpc": {
                "value": 4.54,
                "currency": "USD"
            },
            "url": "http://www.seobook.com/",
            "traffic_percent": 5.52,
            "traffic_cost_percent": 4.28,
            "competition_density": 32,
            "results": 379000,
            "trends": [62, 81, 62, 81, 81, 62, 62, 81, 81, 62, 100, 81],
            "type": "ORGANIC"
        }
    ]
}

In this example, domain=seobook.com becomes url=seobook.com&scope=ROOT_DOMAIN, and database=us becomes country=US&device_type=DESKTOP. position_type=ORGANIC keeps the v3 default of returning organic positions only. The target, database, and month are in meta, not in data.