Seo

Semrush

Learn how to use Semrush with Composio

Overview

SLUG: SEMRUSH

Description

Semrush is a popular SEO tool suite that specializes in keyword research, competitor analysis, and Google Ad campaign optimization.

Authentication Details

generic_api_key
stringRequired

Connecting to Semrush

Create an auth config

Use the dashboard to create an auth config for the Semrush toolkit. This allows you to connect multiple Semrush accounts to Composio for agents to use.

1

Select App

Navigate to the Semrush toolkit page and click “Setup Integration”.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Integration”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2from composio.types import auth_scheme
3
4# Replace these with your actual values
5semrush_auth_config_id = "ac_YOUR_SEMRUSH_CONFIG_ID" # Auth config ID created above
6user_id = "0000-0000-0000"  # UUID from database/app
7
8composio = Composio()
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11    # Replace this with a method to retrieve an API key from the user.
12    # Or supply your own.
13    user_api_key = input("[!] Enter API key")
14
15    connection_request = composio.connected_accounts.initiate(
16        user_id=user_id,
17        auth_config_id=auth_config_id,
18        config={"auth_scheme": "API_KEY", "val": user_api_key}
19    )
20
21    # API Key authentication is immediate - no redirect needed
22    print(f"Successfully connected Semrush for user {user_id}")
23    print(f"Connection status: {connection_request.status}")
24    
25    return connection_request.id
26
27
28connection_id = authenticate_toolkit(user_id, semrush_auth_config_id)
29
30# You can verify the connection using:
31connected_account = composio.connected_accounts.get(connection_id)
32print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Semrush toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["SEMRUSH"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Get keyword difficulty

Description

Determines the keyword difficulty (kd) score (0-100, higher means greater difficulty) for a given phrase in a specific semrush regional database to assess its seo competitiveness.

Action Parameters

database
stringRequired
export_columns
arrayDefaults to ['Ph', 'Kd']
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get ad copies

Description

Retrieves unique ad copies semrush has observed for a specified domain from a regional database, detailing ads seen in google's paid search results.

Action Parameters

database
stringRequired
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to pc_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ph', 'Un', 'Tt', 'Ds', 'Vu', 'Ur', 'Pc', 'Ts']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get anchor texts

Description

Use this action to get a csv report of anchor texts for backlinks pointing to a specified, publicly accessible domain, root domain, or url.

Action Parameters

display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to domains_num_desc
export_columns
arrayDefaults to ['anchor', 'domains_num', 'backlinks_num', 'first_seen', 'last_seen']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get authority score profile

Description

Retrieves the authority score (as) profile for a specified target, showing the count of referring domains that link to the target for each as value from 0 to 100.

Action Parameters

target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Batch comparison

Description

Compares backlink profiles for multiple specified targets (domains, subdomains, or urls) to analyze and compare link-building efforts.

Action Parameters

export_columns
arrayDefaults to ['target', 'target_type', 'ascore', 'backlinks_num', 'domains_num', 'ips_num', 'follows_num', 'nofollows_num', 'texts_num', 'images_num', 'forms_num', 'frames_num']
target_types
arrayRequired
targets
arrayRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Batch keyword overview

Description

Fetches a keyword overview report from a semrush regional database for up to 100 keywords, providing metrics like search volume, cpc, and keyword difficulty.

Action Parameters

database
stringRequired
display_date
string
export_columns
arrayDefaults to ['Ph', 'Nq', 'Cp', 'Co', 'Nr', 'Td', 'In', 'Kd']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Broad match keyword

Description

Fetches broad match keywords for a given phrase; `display sort` and `display filter` parameters are defined but currently not utilized by the api call.

Action Parameters

database
stringRequired
display_date
string
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to nq_desc
export_columns
arrayDefaults to ['Ph', 'Nq', 'Cp', 'Co', 'Nr', 'Td', 'Fk', 'In', 'Kd']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get categories

Description

Retrieves categories and their 0-1 confidence ratings for a specified domain, subdomain, or url, with results sorted by rating.

Action Parameters

display_limit
integer
display_offset
integer
export_columns
arrayDefaults to ['category_name', 'rating']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get categories profile

Description

Retrieves a profile of content categories from referring domains for a specified target, analyzing its first 10,000 referring domains and sorting results by domain count.

Action Parameters

display_limit
integer
display_offset
integer
export_columns
arrayDefaults to ['category_name', 'rating']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get competitor data

Description

Retrieves a customizable csv report of competitors for a specified target (root domain, domain, or url) based on shared backlinks or referring domains, ensuring the target is valid and its type is correctly specified.

Action Parameters

display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to common_backlinks_num_desc
export_columns
arrayDefaults to ['ascore', 'neighbour', 'similarity', 'common_refdomains', 'domains_num', 'backlinks_num']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get domain ad history

Description

Retrieves a domain's 12-month advertising history from semrush (keywords bid on, ad positions, ad copy) for ppc strategy and competitor analysis; most effective when the domain has ad history in the selected database.

Action Parameters

database
stringRequired
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to cv_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ph', 'Dt', 'Po', 'Cp', 'Nq', 'Tr', 'Ur', 'Tt', 'Ds', 'Vu', 'Cv']
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get domain organic pages

Description

Fetches a report on a domain's unique organic pages ranking in google's top 100 search results, with options for specifying database, date, columns, sorting, and filtering.

Action Parameters

database
stringRequired
display_date
string
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to pc_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ur', 'Pc', 'Tg', 'Tr', 'Ipu', 'Ip0', 'Ip1', 'Ip2', 'Ip3', 'Itu', 'It0', 'It1', 'It2', 'It3', 'Sr', 'St']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get domain organic search keywords

Description

Retrieves organic search keywords for a domain from a specified semrush regional database; `display positions` must be set if `display daily=1` for daily updates.

Action Parameters

database
stringRequired
display_daily
integer
display_date
string
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_positions
string
display_positions_type
stringDefaults to organic
display_sort
stringDefaults to po_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ph', 'Po', 'Pp', 'Pd', 'Nq', 'Cp', 'Ur', 'Tr', 'Tg', 'Tc', 'Co', 'Nr', 'Td', 'Kd', 'Fp', 'Fk', 'Ts', 'In', 'Pt']
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get domain organic subdomains

Description

Retrieves a report on subdomains of a given domain that rank in google's top 100 organic search results for a specified regional database.

Action Parameters

database
stringRequired
display_date
string
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to pc_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ur', 'Pc', 'Tg', 'Tr', 'Sr', 'St']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get domain paid search keywords

Description

Fetches keywords driving paid search traffic to a specified, existing domain using a supported semrush regional database.

Action Parameters

database
stringRequired
display_date
string
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_positions
string
display_sort
stringDefaults to po_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ph', 'Po', 'Pp', 'Pd', 'Ab', 'Nq', 'Cp', 'Tg', 'Tr', 'Tc', 'Co', 'Nr', 'Td', 'Tt', 'Ds', 'Vu', 'Ur', 'Ts', 'Un']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get PLA search keywords for a domain

Description

Retrieves product listing ad (pla) search keywords for a specified domain from a semrush regional database.

Action Parameters

database
stringRequired
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to po_desc
domain
stringRequired
export_columns
arrayDefaults to ['Ph', 'Po', 'Pp', 'Pd', 'Nq', 'Sn', 'Ur', 'Tt', 'Pr', 'Ts']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Compare domains

Description

Analyzes keyword rankings by comparing up to five domains to find common, unique, or gap keywords, using specified organic/paid types and comparison logic in the `domains` string.

Action Parameters

database
stringRequired
display_date
string
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to p0_desc
domains
stringRequired
export_columns
arrayDefaults to ['Ph', 'P0', 'P1', 'P2', 'P3', 'P4', 'Nr', 'Cp', 'Nq', 'Kd', 'Co', 'Td']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get historical data

Description

Retrieves monthly historical backlink and referring domain data for a specified root domain, returned as a time series string with newest records first.

Action Parameters

display_limit
integer
display_offset
integer
export_columns
arrayDefaults to ['date', 'backlinks_num', 'domains_num', 'score']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get indexed pages

Description

Retrieves a list of indexed pages from semrush for a specified `target` (root domain, domain, or url) and `target type`, ensuring `target` is publicly accessible, semrush-analyzable, and correctly matches `target type`.

Action Parameters

display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to backlinks_num_desc
export_columns
arrayDefaults to ['source_url', 'source_title', 'response_code', 'backlinks_num', 'domains_num', 'last_seen', 'external_num', 'internal_num']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get keywords ads history

Description

Fetches a historical report (last 12 months) of domains advertising on a specified keyword in google ads, optionally for a specific month ('yyyymm15') or the most recent period, returning raw csv-like data.

Action Parameters

database
stringRequired
display_date
string
display_limit
integerDefaults to 10000
display_offset
integer
export_columns
arrayDefaults to ['Dn', 'Dt', 'Po', 'Ur', 'Tt', 'Ds', 'Vu', 'At', 'Ac', 'Ad']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Keyword overview all databases

Description

Fetches a keyword overview from semrush for a specified phrase, including metrics like search volume, cpc, and competition.

Action Parameters

database
string
export_columns
arrayDefaults to ['Dt', 'Db', 'Ph', 'Nq', 'Cp', 'Co', 'Nr', 'In', 'Kd']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get keyword overview for one database

Description

Fetches a keyword summary for a specified phrase from a chosen regional database.

Action Parameters

database
stringRequired
display_date
string
export_columns
arrayDefaults to ['Ph', 'Nq', 'Cp', 'Co', 'Nr', 'Td', 'In', 'Kd']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get organic results

Description

Retrieves up to 100,000 domains and urls from google's top 100 organic search results for a keyword and region, returning a raw string; use `display date` in 'yyyymm15' format (day must be '15') for historical data.

Action Parameters

database
stringRequired
display_date
string
display_limit
integerDefaults to 10000
display_offset
integer
export_columns
arrayDefaults to ['Po', 'Pt', 'Dn', 'Ur', 'Fk', 'Fp', 'Fl']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired
positions_type
stringDefaults to organic

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get paid search results

Description

Fetches domains ranking in google's paid search results (adwords) for a specified keyword and regional database.

Action Parameters

database
stringRequired
display_date
string
display_limit
integerDefaults to 10000
display_offset
integer
export_columns
arrayDefaults to ['Dn', 'Ur', 'Vu']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Phrase questions

Description

Fetches question-format keywords semantically related to a given query phrase for a specified regional database, aiding in understanding user search intent and discovering content ideas.

Action Parameters

database
stringRequired
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to nq_desc
export_columns
arrayDefaults to ['Ph', 'Nq', 'Cp', 'Co', 'Nr', 'Td', 'In', 'Kd']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1
phrase
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get PLA competitors

Description

Retrieves domains competing with a specified domain in google's product listing ads (pla) from a given semrush regional database.

Action Parameters

database
stringRequired
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to np_desc
domain
stringRequired
export_columns
arrayDefaults to ['Dn', 'Cr', 'Np', 'Sh', 'Ad', 'At', 'Ac', 'Or']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get PLA copies

Description

Fetches product listing ad (pla) copies that semrush observed for a domain in google's paid search results.

Action Parameters

database
stringRequired
display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to pr_desc
domain
stringRequired
export_columns
arrayDefaults to ['Tt', 'Pr', 'Ur', 'Pc', 'Un', 'Ts']
export_decode
integerDefaults to 1
export_escape
integerDefaults to 1

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get referring domains

Description

Retrieves a report as a text string (e.g., csv) listing domains that link to a target, with options to filter by type (not value).

Action Parameters

display_filter
array
display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to backlinks_num_desc
export_columns
arrayDefaults to ['domain_ascore', 'domain', 'backlinks_num', 'ip', 'country', 'first_seen', 'last_seen']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get referring domains by country

Description

Generates a csv report detailing the geographic distribution of referring domains (by country, determined via ip address) for a specified, publicly accessible target.

Action Parameters

display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to domains_num_desc
export_columns
arrayDefaults to ['country', 'domains_num', 'backlinks_num']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Referring i ps

Description

Fetches ip addresses that are sources of backlinks for a specified target domain, root domain, or url.

Action Parameters

display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to backlinks_num_desc
export_columns
arrayDefaults to ['ip', 'country', 'domains_num', 'backlinks_num', 'first_seen', 'last_seen']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired

Tool Name: Get TLD distribution

Description

Fetches a report on the top-level domain (tld) distribution of referring domains for a specified target, useful for analyzing geographic or categorical backlink diversity.

Action Parameters

display_limit
integerDefaults to 10000
display_offset
integer
display_sort
stringDefaults to domains_num_desc
export_columns
arrayDefaults to ['zone', 'domains_num', 'backlinks_num']
target
stringRequired
target_type
stringRequired

Action Response

data
stringRequired
error
string
successful
booleanRequired