# semrush.seo.keywords.difficulty

Keyword difficulty index of up to 100 keywords by country

> This report provides keyword difficulty, an index that helps to estimate how difficult it would be to seize competitors’ positions in organic search within Google’s top 10 with a queried search term.

Page: https://telipot.com/catalog/tasks/semrush.seo.keywords.difficulty · Markdown: https://telipot.com/catalog/tasks/semrush.seo.keywords.difficulty/md · JSON: https://telipot.com/catalog/tasks/semrush.seo.keywords.difficulty/json

| Field | Value |
| --- | --- |
| provider | [Semrush](https://telipot.com/catalog/providers/semrush) `semrush` |
| capability | [`seo.keywords.difficulty`](https://telipot.com/catalog/capabilities/seo.keywords.difficulty) |
| kind | data |
| tier | core |
| price | Semrush API units (50 API units / result · docs) |
| price note | 50 API units per line returned, one line per keyword. Semrush does not charge a request that returns no data. Semrush publishes no USD price per API unit. |
| identity | Your plan |
| auth | `api_key · in query as key` |
| scope | any_account |
| principal | organization |
| required_scopes | none |
| retention | standard |
| route | `GET https://api.semrush.com/` |
| verification | Not verified yet. Not checked yet. We test with a real request before we mark it. |
| status | live |
| docs | https://developer.semrush.com/api/v3/seo/keyword-reports/#keyword-difficulty |

## Preview the price · nothing runs

```bash
telipot run semrush.seo.keywords.difficulty \
  --input-json '{"type":"phrase_kdi","phrase":"seo","database":"us","export_columns":"Ph,Kd"}' \
  --quote
```

## Run it

```bash
telipot run semrush.seo.keywords.difficulty \
  --input-json '{"type":"phrase_kdi","phrase":"seo","database":"us","export_columns":"Ph,Kd"}'
```

```bash
curl https://api.telipot.com/v1/tasks/semrush.seo.keywords.difficulty/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"phrase_kdi","phrase":"seo","database":"us","export_columns":"Ph,Kd"}'
```

## Input

| Field | In | Type | Required | Constraints | Note |
| --- | --- | --- | --- | --- | --- |
| `type` | queryParams | string | yes | const "phrase_kdi" | Fixed. Selects the Keyword Difficulty report. |
| `phrase` | queryParams | string | yes |  | From 1 to 100 keywords separated by semicolons. |
| `database` | queryParams | string | yes |  | Two-letter regional database code, such as us, uk, ca, de or fr. Keyword reports accept the plain two-letter codes only, not the mobile- and -ext variants. The full list is under Databases in the SEO API overview. |
| `export_columns` | queryParams | string | no | default "Ph,Kd" | Comma-separated column codes, in the order wanted. Ph Keyword, Kd Keyword Difficulty Index (0 to 100, higher is harder). |

## Input schema

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Fixed. Selects the Keyword Difficulty report.",
      "const": "phrase_kdi"
    },
    "phrase": {
      "type": "string",
      "description": "From 1 to 100 keywords separated by semicolons.",
      "examples": [
        "seo;ebay"
      ]
    },
    "database": {
      "type": "string",
      "description": "Two-letter regional database code, such as us, uk, ca, de or fr. Keyword reports accept the plain two-letter codes only, not the mobile- and -ext variants. The full list is under Databases in the SEO API overview.",
      "examples": [
        "us"
      ]
    },
    "export_columns": {
      "type": "string",
      "description": "Comma-separated column codes, in the order wanted. Ph Keyword, Kd Keyword Difficulty Index (0 to 100, higher is harder).",
      "default": "Ph,Kd"
    }
  },
  "required": [
    "type",
    "phrase",
    "database"
  ],
  "additionalProperties": false
}
```

## Output schema

```json
{
  "type": "string",
  "pattern": "^(?!\\s*ERROR)",
  "description": "CSV text: a header line of column names, then one line per keyword, columns separated by semicolons, in the order of export_columns. A body that starts with ERROR is a failure, for example ERROR 50 :: NOTHING FOUND."
}
```