Quick start

In this article, you’ll learn how to get your API key, construct and test an API call, and retrieve and process data with Semrush API Version 4.

Jump to Get API keyGet API key

Your API key lets you send requests through the Semrush API.

To get your key:

1. Click the icon at the top right of the Semrush interface to access your profile.
2. In the My profile sidebar, select API Keys. You’ll see the list of your autogenerated Version 3 and Version 4 API keys.
3. To retrieve the Backlinks report, create a new v4 API key.
   1. Select + Create API key.
   2. Specify a key name.
   3. Select necessary permissions.
   4. Optionally, set an expiration date (TTL).
4. Copy the key and store it securely.

Before making your first request, check your API unit balance to ensure it’s sufficient for your use case.

Jump to Construct your API callConstruct your API call

Jump to Review request exampleReview request example

All API methods include request examples, providing a great starting point for your requests. You’ll find them in the Request example panel on each method page, such as Backlinks.

curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/backlinks/v1/links?url=example.com&scope=ROOT_DOMAIN&fields=anchor,domain_score,page_score&order_by=page_score&direction=DESC&limit=10"

Jump to Construct your API callConstruct your API call

1. Start with the base URL. For the Backlinks request, it’s https://api.semrush.com/apis/v4/backlinks/v1/links.
2. Authenticate the request. Pass your API key in the Authorization header: Authorization: Apikey YOUR_API_KEY. Replace YOUR_API_KEY with your API key. Alternatively, pass it as the key query parameter.
3. Add ? to start the query parameters.
4. Enter the required parameters, using & to separate them:
   1. Provide the target: url=example.com
   2. Specify the scope: scope=ROOT_DOMAIN
5. Include any additional query parameters as needed. For example:
   1. Return only specific response fields: fields=backlinks_count,domains_count,score
   2. Set the response format: format=csv. Version 4 methods return responses in json (default) or csv.
6. Put together the full request URL.

The base URL and parameters vary by method. Always check the method page for the exact endpoint, required parameters, and price in API units.

Jump to (Optional) Limit, sort, and filter results(Optional) Limit, sort, and filter results

Many Version 4 methods that return lists, including Backlinks, provide query parameters for limiting, sorting, and filtering results.

Jump to Limit resultsLimit results

Use the limit and offset query parameters to page through results. Set limit to cap the number of rows returned in a response and save on API units, and offset to skip rows. For example, adding &limit=10 returns only the top 10 results.

Jump to Sort resultsSort results

Sort results with the order_by and direction parameters. Set order_by to a response field and direction to ASC or DESC.

Jump to Filter resultsFilter results

When standard parameters aren’t enough, use the filter parameter for advanced conditions with operators such as >, LIKE, CONTAINS, and logical AND or OR. For example, to return only dofollow backlinks first seen since 2024:

filter=first_seen_at > '2024-01-01' AND is_nofollow = false

For the full syntax and supported operators, refer to Advanced filtering.

Jump to Test your API callTest your API call

Before integrating the Semrush API into your workflow, test your API request using Postman or cURL to ensure it returns the expected data.

1. Verify authentication: Ensure the request includes the correct API credentials.
2. Request only relevant data: Optimize performance by using filters and query parameters.
3. Review API response: Confirm that the structure and content match your expectations.

Jump to Retrieve and process dataRetrieve and process data

To automate data retrieval from the Semrush API, create a script in your preferred programming language that handles API calls, data processing, storage, and integration with BI tools or other platforms.

Jump to Step 1. Fetch data from the APIStep 1. Fetch data from the API

Ensure the script handles authentication, respects rate limits, and fetches only relevant data.

Jump to Step 2. Handle errorsStep 2. Handle errors

Implement error handling with logging and retry mechanisms for failed or incomplete requests. Version 4 responses include a meta.success flag and an error object with a retryable field you can use to decide whether to retry.

Each API has its own error format—refer to the error messages section for the API you’re using: SEO API, Local API, and Projects API.

Jump to Step 3. Process the responseStep 3. Process the response

Convert or parse the response into your chosen format.

Jump to Step 4. Store or transfer the dataStep 4. Store or transfer the data

You can store Semrush API output locally or transfer it to external systems:

• Cloud storage such as Amazon S3 and Google Cloud Storage
• Databases and data warehouses such as BigQuery and Snowflake
• SFTP servers

Jump to Step 5. Integrate with BI and CRM toolsStep 5. Integrate with BI and CRM tools

You can load processed Semrush data into business intelligence platforms for visualization and real-time insight:

• Dashboard tools such as Power BI, Tableau, and Looker Studio
• CRM platforms such as Salesforce

You can use third-party connectors such as Supermetrics, Workato, or Zapier to simplify integration with these tools without heavy development.

Jump to Step 6. Automate recurring data updatesStep 6. Automate recurring data updates

To keep your data up-to-date, you can use:

• OS-level schedulers like Task Scheduler (Windows) or cron (Linux/macOS) to run scripts at predefined intervals.
• Third-party automation tools to regularly trigger API calls.