Keyword reports

Use the Semrush Keyword reports API v4 to retrieve search volume, keyword difficulty, search intent, CPC, competition, trends, and SERP feature data for a keyword, and to find related and broad-match keyword ideas.

Jump to Get Keyword MetricsGet Keyword Metrics

Price: 20 API units per request

Returns metrics from the latest snapshot available for the specified month.

Jump to EndpointEndpoint

GEThttps://api.semrush.com/apis/v4/keywords/v1/metrics

Query parameters

keywordRequired

Keyword to get metrics for. Length must be between 1 and 255 characters.

Example: seo tools

Value/Type: string

countryRequired

Two-letter country code (ISO 3166-1 alpha-2) for which the metrics are returned.

Supported values: AF, AL, DZ, AO, AR, AM, AU, AT, AZ, BS, BH, BD, BY, BE, BZ, BO, BA, BW, BR, BN, BG, KH, CM, CA, CV, CL, CO, CR, HR, CY, CZ, CD, DK, DO, EC, EG, SV, EE, ET, FI, FR, GE, DE, GH, GR, GT, GY, HT, HN, HK, HU, IS, IN, ID, IE, IL, IT, JM, JP, JO, KZ, KW, LV, LB, LY, LT, LU, MG, MY, MT, MU, MX, MD, MN, ME, MA, MZ, NA, NP, NL, NZ, NI, NG, NO, OM, PK, PA, PY, PE, PH, PL, PT, QA, RO, RU, SA, SN, RS, SG, SK, SI, ZA, KR, ES, LK, SE, CH, TW, TH, TT, TN, TR, UA, AE, UK, US, UY, VE, VN, ZM, ZW.

Example: US

Value/Type: string

month

Monthly snapshot for which the data is returned. Format: YYYY-MM. Minimum: 2012-01.

If not set, or set to the current or a future month, the latest available data is returned. The month of the returned snapshot is shown in meta.month.

Example: 2024-01

Value/Type: string

format

Response format. Supported values: json (default), csv.

Value/Type: string

Response Parameters

meta

Response metadata describing the request context.

Value/Type: object

data

SEO and PPC metrics for the keyword. If no data is available for the keyword, data contains only empty intents, trends, and serp_features arrays.

Value/Type: object

Request example
curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/metrics?keyword=seo%20tools&country=US&month=2024-01"
Response example
JSON
{
  "meta": {
      "country": "US",
      "keyword": "seo tools",
      "month": "2024-01",
      "request_id": "4fb1773ec2a8d61a0407f464599f897c",
      "status_code": 200,
      "success": true
  },
  "data": {
      "search_volume": 60500,
      "cpc": 1245,
      "keyword_difficulty": 74,
      "competitive_density": 78,
      "number_of_results": 1850000000,
      "intents": ["COMMERCIAL", "INFORMATIONAL"],
      "trends": [82, 78, 85, 90, 88, 92, 95, 100, 96, 91, 87, 84],
      "serp_features": ["SITELINKS", "PEOPLE_ALSO_ASK", "AI_OVERVIEW", "RELATED_SEARCHES"]
  }
}
Response example
CSV
search_volume;cpc;keyword_difficulty;competitive_density;number_of_results;intents;trends;serp_features
60500;1245;74;78;1850000000;COMMERCIAL,INFORMATIONAL;82,78,85,90,88,92,95,100,96,91,87,84;SITELINKS,PEOPLE_ALSO_ASK,AI_OVERVIEW,RELATED_SEARCHES

Jump to List Broad MatchList Broad Match

Price: 40 API units per line

Returns broad-match keywords and alternate queries that contain the seed keyword in any variation and word order—the widest set of keyword ideas.

Jump to EndpointEndpoint

GEThttps://api.semrush.com/apis/v4/keywords/v1/ideas/broad-match

Query parameters

keywordRequired

Seed keyword to find keyword ideas for. Length must be between 1 and 255 characters.

Example: seo tools

Value/Type: string

countryRequired

Two-letter country code (ISO 3166-1 alpha-2) for which keyword ideas are returned.

Supported values: AF, AL, DZ, AO, AR, AM, AU, AT, AZ, BS, BH, BD, BY, BE, BZ, BO, BA, BW, BR, BN, BG, KH, CM, CA, CV, CL, CO, CR, HR, CY, CZ, CD, DK, DO, EC, EG, SV, EE, ET, FI, FR, GE, DE, GH, GR, GT, GY, HT, HN, HK, HU, IS, IN, ID, IE, IL, IT, JM, JP, JO, KZ, KW, LV, LB, LY, LT, LU, MG, MY, MT, MU, MX, MD, MN, ME, MA, MZ, NA, NP, NL, NZ, NI, NG, NO, OM, PK, PA, PY, PE, PH, PL, PT, QA, RO, RU, SA, SN, RS, SG, SK, SI, ZA, KR, ES, LK, SE, CH, TW, TH, TT, TN, TR, UA, AE, UK, US, UY, VE, VN, ZM, ZW.

Example: US

Value/Type: string

limit

Maximum number of keywords to return. Min: 1. Default: 100. Max: 1000.

Value/Type: integer

offset

Number of keywords to skip, for page-based navigation. Default: 0. Deep pagination is capped: offset + limit must not exceed 50000, so results beyond the 50000th entry cannot be retrieved.

Value/Type: integer

order_by

Field to sort by. Note: sorting by serp_features orders by the number of SERP features returned for each keyword.

Supported values: keyword, search_volume, cpc, keyword_difficulty, competitive_density, number_of_results, serp_features.

Default: search_volume in DESC direction. If you set order_by, also set direction.

Example: search_volume

Value/Type: string

direction

Sort direction. Required if order_by is set, and can only be used together with order_by.

Supported values: ASC, DESC.

Example: DESC

Value/Type: string

filter

Advanced filter expression over response fields. Any field from the response except trends can be used in the expression, plus words_count, the number of words in the keyword, which is not returned in the response. Use field names without the metrics. prefix. Combine conditions with AND and OR, and use parentheses for grouping; AND takes precedence over OR. Numeric fields support =, !=, >, >=, <, and <= with non-negative integer values; cpc is in USD cents. Use HAS to match a value in intents or serp_features. For keyword, use =, !=, CONTAINS, or WORD_MATCH, which matches keywords containing all words of the value in any form and order. String values must be in double quotes; keyword values are case-sensitive.

Examples: search_volume > 100 AND keyword_difficulty <= 49, intents HAS "INFORMATIONAL", keyword CONTAINS "free" AND words_count >= 3

Value/Type: string

is_question

Question filter. true keeps only question keywords (who, what, how, etc.); false keeps only non-question keywords. When not set, no question filtering is applied.

Value/Type: boolean

format

Response format. Supported values: json (default), csv.

Value/Type: string

Response Parameters

meta

Response metadata describing the request context.

Value/Type: object

data

Array of broad-match keyword objects, each containing keyword and its metrics.

Value/Type: object[]

Request example
curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/ideas/broad-match?keyword=seo%20tools&country=US&limit=10&order_by=search_volume&direction=DESC"
Response example
JSON
{
  "meta": {
      "country": "US",
      "filter": "",
      "is_question": false,
      "keyword": "seo tools",
      "limit": 10,
      "offset": 0,
      "request_id": "4fb1773ec2a8d61a0407f464599f897c",
      "status_code": 200,
      "success": true
  },
  "data": [
      {
          "keyword": "seo tools",
          "metrics": {
              "search_volume": 60500,
              "cpc": 1245,
              "keyword_difficulty": 74,
              "competitive_density": 78,
              "number_of_results": 1850000000,
              "intents": ["COMMERCIAL", "INFORMATIONAL"],
              "trends": [82, 78, 85, 90, 88, 92, 95, 100, 96, 91, 87, 84],
              "serp_features": ["SITELINKS", "PEOPLE_ALSO_ASK", "AI_OVERVIEW", "RELATED_SEARCHES"]
          }
      },
      {
          "keyword": "best seo tools",
          "metrics": {
              "search_volume": 18200,
              "cpc": 1560,
              "keyword_difficulty": 68,
              "competitive_density": 75,
              "number_of_results": 920000000,
              "intents": ["COMMERCIAL"],
              "trends": [71, 68, 72, 79, 76, 81, 88, 93, 89, 84, 76, 72],
              "serp_features": ["SITELINKS", "PEOPLE_ALSO_ASK"]
          }
      },
      {
          "keyword": "free seo tools",
          "metrics": {
              "search_volume": 12100,
              "cpc": 892,
              "keyword_difficulty": 61,
              "competitive_density": 68,
              "number_of_results": 580000000,
              "intents": ["COMMERCIAL", "INFORMATIONAL"],
              "trends": [65, 62, 67, 73, 70, 76, 82, 88, 81, 75, 68, 64],
              "serp_features": ["SITELINKS", "RELATED_SEARCHES"]
          }
      }
  ]
}
Response example
CSV
keyword;search_volume;cpc;keyword_difficulty;competitive_density;number_of_results;intents;trends;serp_features
seo tools;60500;1245;74;78;1850000000;COMMERCIAL,INFORMATIONAL;82,78,85,90,88,92,95,100,96,91,87,84;SITELINKS,PEOPLE_ALSO_ASK,AI_OVERVIEW,RELATED_SEARCHES
best seo tools;18200;1560;68;75;920000000;COMMERCIAL;71,68,72,79,76,81,88,93,89,84,76,72;SITELINKS,PEOPLE_ALSO_ASK
free seo tools;12100;892;61;68;580000000;COMMERCIAL,INFORMATIONAL;65,62,67,73,70,76,82,88,81,75,68,64;SITELINKS,RELATED_SEARCHES

Price: 40 API units per line

Returns semantically related keywords, synonyms, and variations for a seed keyword, along with SEO and PPC metrics to support keyword research.

Jump to EndpointEndpoint

GEThttps://api.semrush.com/apis/v4/keywords/v1/ideas/related

Query parameters

keywordRequired

Seed keyword to find related ideas for. Length must be between 1 and 255 characters.

Example: seo tools

Value/Type: string

countryRequired

Two-letter country code (ISO 3166-1 alpha-2) for which the related keyword ideas are returned.

Supported values: AF, AL, DZ, AO, AR, AM, AU, AT, AZ, BS, BH, BD, BY, BE, BZ, BO, BA, BW, BR, BN, BG, KH, CM, CA, CV, CL, CO, CR, HR, CY, CZ, CD, DK, DO, EC, EG, SV, EE, ET, FI, FR, GE, DE, GH, GR, GT, GY, HT, HN, HK, HU, IS, IN, ID, IE, IL, IT, JM, JP, JO, KZ, KW, LV, LB, LY, LT, LU, MG, MY, MT, MU, MX, MD, MN, ME, MA, MZ, NA, NP, NL, NZ, NI, NG, NO, OM, PK, PA, PY, PE, PH, PL, PT, QA, RO, RU, SA, SN, RS, SG, SK, SI, ZA, KR, ES, LK, SE, CH, TW, TH, TT, TN, TR, UA, AE, UK, US, UY, VE, VN, ZM, ZW.

Example: US

Value/Type: string

limit

Maximum number of keywords to return. Min: 1. Default: 100. Max: 1000.

Value/Type: integer

offset

Number of keywords to skip, for page-based navigation. Default: 0. Deep pagination is capped: offset + limit must not exceed 50000, so results beyond the 50000th entry cannot be retrieved.

Value/Type: integer

order_by

Field to sort by. Sorting by serp_features orders by the number of SERP features returned for each keyword.

Supported values: keyword, search_volume, cpc, keyword_difficulty, competitive_density, number_of_results, serp_features, relevance.

Default: search_volume in DESC direction. If you set order_by, also set direction.

Example: relevance

Value/Type: string

direction

Sort direction. Required if order_by is set, and can only be used together with order_by.

Supported values: ASC, DESC.

Example: DESC

Value/Type: string

filter

Advanced filter expression over response fields. Any field from the response except trends can be used in the expression, plus words_count, the number of words in the keyword, which is not returned in the response. Use field names without the metrics. prefix. Combine conditions with AND and OR, and use parentheses for grouping; AND takes precedence over OR. Numeric fields support =, !=, >, >=, <, and <= with non-negative integer values; cpc is in USD cents. Use HAS to match a value in intents or serp_features. For keyword, use =, !=, CONTAINS, or WORD_MATCH, which matches keywords containing all words of the value in any form and order. String values must be in double quotes; keyword values are case-sensitive.

Examples: search_volume > 100 AND keyword_difficulty <= 49, relevance >= 50 AND intents HAS "INFORMATIONAL", keyword WORD_MATCH "free tools" OR serp_features HAS "FEATURED_SNIPPET"

Value/Type: string

is_question

If set to true, returns only question keywords (who, what, how, etc.). If false, returns only non-question keywords. If not set, no question filtering is applied.

Value/Type: boolean

format

Response format. Supported values: json (default), csv.

Value/Type: string

Response Parameters

meta

Response metadata.

Value/Type: object

data

Array of related keywords with their metrics and relevance scores.

Value/Type: object[]

Request example
curl -H 'Authorization: Apikey YOUR_API_KEY' "https://api.semrush.com/apis/v4/keywords/v1/ideas/related?keyword=seo%20tools&country=US&limit=10&order_by=relevance&direction=DESC"
Response example
JSON
{
  "meta": {
      "country": "US",
      "filter": "",
      "is_question": false,
      "keyword": "seo tools",
      "limit": 10,
      "offset": 0,
      "request_id": "4fb1773ec2a8d61a0407f464599f897c",
      "status_code": 200,
      "success": true
  },
  "data": [
      {
          "keyword": "best seo tools",
          "metrics": {
              "search_volume": 32100,
              "cpc": 895,
              "keyword_difficulty": 72,
              "competitive_density": 81,
              "number_of_results": 2100000000,
              "intents": ["COMMERCIAL", "INFORMATIONAL"],
              "trends": [75, 78, 82, 85, 88, 90, 92, 94, 96, 98, 100, 96],
              "serp_features": ["SITELINKS", "PEOPLE_ALSO_ASK", "RELATED_SEARCHES"]
          },
          "relevance": 95
      },
      {
          "keyword": "free seo tools",
          "metrics": {
              "search_volume": 28400,
              "cpc": 642,
              "keyword_difficulty": 68,
              "competitive_density": 76,
              "number_of_results": 1950000000,
              "intents": ["COMMERCIAL", "INFORMATIONAL"],
              "trends": [78, 80, 83, 86, 89, 91, 93, 95, 97, 99, 100, 97],
              "serp_features": ["SITELINKS", "FEATURED_SNIPPET", "PEOPLE_ALSO_ASK"]
          },
          "relevance": 88
      },
      {
          "keyword": "seo tools for beginners",
          "metrics": {
              "search_volume": 15600,
              "cpc": 724,
              "keyword_difficulty": 65,
              "competitive_density": 71,
              "number_of_results": 1210000000,
              "intents": ["INFORMATIONAL", "COMMERCIAL"],
              "trends": [68, 70, 72, 74, 76, 78, 80, 82, 84, 86, 88, 90],
              "serp_features": ["SITELINKS", "PEOPLE_ALSO_ASK", "RELATED_SEARCHES"]
          },
          "relevance": 82
      }
  ]
}
Response example
CSV
keyword;search_volume;cpc;keyword_difficulty;competitive_density;number_of_results;intents;trends;serp_features;relevance
best seo tools;32100;895;72;81;2100000000;COMMERCIAL,INFORMATIONAL;75,78,82,85,88,90,92,94,96,98,100,96;SITELINKS,PEOPLE_ALSO_ASK,RELATED_SEARCHES;95
free seo tools;28400;642;68;76;1950000000;COMMERCIAL,INFORMATIONAL;78,80,83,86,89,91,93,95,97,99,100,97;SITELINKS,FEATURED_SNIPPET,PEOPLE_ALSO_ASK;88
seo tools for beginners;15600;724;65;71;1210000000;INFORMATIONAL,COMMERCIAL;68,70,72,74,76,78,80,82,84,86,88,90;SITELINKS,PEOPLE_ALSO_ASK,RELATED_SEARCHES;82

Last updated: November 13, 2026

Was this page helpful?