### Install and Configure Serpstat MCP Server (Node.js)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

This snippet shows how to install the Serpstat MCP server using npx and configure it within an AI assistant's configuration. It highlights the command-line installation and environment variable setup for the API token.

```json
{
  "mcpServers": {
    "serpstat": {
      "command": "npx",
      "args": ["-y", "@serpstat/serpstat-mcp-server"],
      "env": { "SERPSTAT_API_TOKEN": "your_serpstat_api_token_here" }
    }
  }
}
```

--------------------------------

### Serpstat API Response Example (JSON)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/v91plc4ro30g6-get-task-result

This is an example of a successful JSON response from the Serpstat API for a keyword data retrieval task. It includes pagination details (total, page, pageSize), task metadata, and an array of keyword objects, each with properties like keyword, searchVolume, and competition.

```json
{
  "id": "123",
  "result": {
    "total": 6,
    "page": 1,
    "pageSize": 10,
    "taskMeta": {
      "typeId": "1",
      "seId": "1",
      "regionId": "2840",
      "match": "exact"
    },
    "keywords": [
      {
        "keyword": "iphone",
        "keyword.raw": "iphone",
        "status": 2,
        "cost": 2.66,
        "searchVolume": 1220000,
        "searchVolumeHistory": [
          {
            "date": "2024-02-01T00:00:00",
            "value": 1000000
          },
          {
            "date": "2024-03-01T00:00:00",
            "value": 1000000
          },
          {
            "date": "2024-04-01T00:00:00",
            "value": 1000000
          },
          {
            "date": "2024-05-01T00:00:00",
            "value": 1220000
          },
          {
            "date": "2024-06-01T00:00:00",
            "value": 1220000
          },
          {
            "date": "2024-07-01T00:00:00",
            "value": 1500000
          },
          {
            "date": "2024-08-01T00:00:00",
            "value": 1500000
          },
          {
            "date": "2024-09-01T00:00:00",
            "value": 1830000
          },
          {
            "date": "2024-10-01T00:00:00",
            "value": 1220000
          },
          {
            "date": "2024-11-01T00:00:00",
            "value": 1220000
          },
          {
            "date": "2024-12-01T00:00:00",
            "value": 1500000
          },
          {
            "date": "2025-01-01T00:00:00",
            "value": 1220000
          }
        ],
        "competition": 100
      },
      {
        "keyword": "iphone X",
        "keyword.raw": "iphone X",
        "status": 2,
        "cost": 0.66,
        "searchVolume": 135000,
        "searchVolumeHistory": [
          {
            "date": "2024-02-01T00:00:00",
            "value": 201000
          },
          {
            "date": "2024-03-01T00:00:00",
            "value": 201000
          },
          {
            "date": "2024-04-01T00:00:00",
            "value": 165000
          },
          {
            "date": "2024-05-01T00:00:00",
            "value": 165000
          },
          {
            "date": "2024-06-01T00:00:00",
            "value": 165000
          },
          {
            "date": "2024-07-01T00:00:00",
            "value": 110000
          },
          {
            "date": "2024-08-01T00:00:00",
            "value": 110000
          },
          {
            "date": "2024-09-01T00:00:00",
            "value": 165000
          },
          {
            "date": "2024-10-01T00:00:00",
            "value": 110000
          },
          {
            "date": "2024-11-01T00:00:00",
            "value": 110000
          },
          {
            "date": "2024-12-01T00:00:00",
            "value": 110000
          },
          {
            "date": "2025-01-01T00:00:00",
            "value": 90500
          }
        ],
        "competition": 89
      },
      {
        "keyword": "iphone 11",
        "keyword.raw": "iphone 11",
        "status": 2,
        "cost": 0.24,
        "searchVolume": 450000,
        "searchVolumeHistory": [
          {
            "date": "2024-02-01T00:00:00",
            "value": 1000000
          }
```

--------------------------------

### API Request Body Example

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/50bwxkycuia8p-get-task-result

An example of the JSON payload required to request task results from the Serpstat API. It specifies the request ID, method, and parameters including the task ID and page number.

```json
{
  "id": "123",
  "method": "tasks.getTaskResult",
  "params": {
    "taskId": 5484945,
    "page": 1
  }
}
```

--------------------------------

### Example of Blocked vs. Processed Keywords

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/139902435d58c-serp-scraper-api

Illustrates keywords that are blocked from processing due to invalidity or exceeding limits, and keywords that are successfully processed or automatically cleaned by the system. It highlights valid keyword characteristics and provides examples of cleaning.

```text
**Blocked keywords (will not be processed):**
" " ← Empty keyword (after trimming)
"!!!" ← Becomes empty after symbol filtration
"this is a very long keyword that exceeds the maximum allowed length limit..." ← Keyword longer than 2000 characters

**Note** : For standard SERP parsing, there are **NO** restrictions on:
  * Number-only keywords (e.g., "123456") ✅ ALLOWED
  * Number of words per keyword ✅ ALLOWED
  * Length of individual words ✅ ALLOWED

**Successfully processed keywords:**
"123456789" ← Numbers-only keywords are ALLOWED
"screen resolution" ← Regular keywords
"examplecom" ← Domains after command and symbol removal (dots removed)
"this is a very long keyword with many many many many many words" ← No word limit
"supercalifragilisticexpialidociousantidisestablishmentarianism" ← No individual word length limit

**Auto-cleaned keywords:**
Original: "keyword with +special symbols"
Processed: "keyword with special symbols"
Original: "filetype:pdf document search"
Processed: "pdf document search"
Original: "site:example.com keyword search"
Processed: BLOCKED (contains forbidden command site:)
Original: "best coffee shops 😊☕ in Paris…"
Processed: "best coffee shops in Paris"
Original: "daterange:20220101-20221231 ~news reports"
Processed: "20220101-20221231 news reports"
Original: "allinanchor:\"buy shoes\" (cheap)"
Processed: "buy shoes cheap"
Original: "url:example.com title:test inurl:page"
Processed: BLOCKED (contains forbidden commands url:, title:, inurl:)
Original: "document.pdf search terms"
Processed: "documentpdf search terms"
Original: "cache:example.com"
Processed: BLOCKED (contains forbidden command cache:)
Original: "!!!"
Processed: BLOCKED (contains forbidden symbols ! ! !)

```

--------------------------------

### API Response Example

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/50bwxkycuia8p-get-task-result

A sample JSON response from the Serpstat API after requesting task results. This response includes task metadata such as SE ID, country ID, region ID, and device type, along with a detailed array of keyword data.

```json
{
  "id": "123",
  "result": {
    "task_meta": {
      "se_id": "1",
      "country_id": "23",
      "region_id": "21176",
      "device_type_id": "1"
    },
    "tops": [
      {
        "keyword_id": "706657334",
        "keyword": "burger",
        "keyword_data": {
          "top": [
            {
              "url": "https://www.kayak.com/Cheap-Metairie-Car-Rentals.20715.cars.ksp",
              "domain": "kayak.com",
              "subdomain": "www.kayak.com",
              "position": 1,
              "title": "Metairie car rentals from $37/day",
              "title_length": 33,
              "snippet": "In the past 72 hours, the cheapest rental cars were found at Thrifty ($28.70/day), Hertz ($44.97/day) and Enterprise Rent-A-Car ($47.52/day). Starting from $36.70",
              "snippet_length": 162,
              "breadcrumbs": "https://www.kayak.com › Cheap-Metairie-Car-Rentals.2...",
              "types": [
                "snip_breadcrumbs",
                "snip_image_thumbnail",
                "snip_url_in_aio"
              ],
              "spec_elements": [
                {
                  "anchor": null,
                  "content": "https://www.kayak.com › Cheap-Metairie-Car-Rentals.2...",
                  "href": null,
                  "sort_number": 0,
                  "type": "snip_breadcrumbs"
                },
                {
                  "anchor": null,
                  "content": null,
                  "href": null,
                  "sort_number": 1,
                  "type": "snip_image_thumbnail"
                },
                {
                  "anchor": null,
                  "content": null,
                  "href": null,
                  "sort_number": 2,
                  "type": "snip_url_in_aio"
                }
              ]
            }
          ],
          "ads": {
            "1": [
              {
                "url": "https://www.avis.com/en/locations/find-a-location",
                "domain": "avis.com",
                "subdomain": "www.avis.com",
                "position": 1,
                "title": "Avis Rent a Car | Avis® Car Rental",
                "text": "Avis has a wide range of car options and thousands of convenient locations",
                "breadcrumbs": "https://www.avis.com"
              }
            ],
            "2": [],
            "3": []
          },
          "results": 1050000,
          "right_spell": "",
          "types": [
            "related_search",
            "also_asks",
            "ai_overview",
            "local_pack",
            "pic",
            "ads_top"
          ],
          "top_features_content": [
            {
              "LocalPack": {
                "LocalPackSnippet": {
                  "localpack": [
                    {
                      "title": "Enterprise Rent-A-Car",
                      "ads": false,
                      "thumbnail": false,
                      "extensions": [
                        "Car rental agency",
                        "Metairie, LA",
                        "(504) 457-0180",
                        "Closed",
                        "Opens 7:30 AM"
                      ],
                      "rating": "4.2",
                      "review": "194",
                      "pricing": null,
                      "wrapped": "Cannot recommend highly enough.",
                      "options": null,
                      "position": 1
                    },
                    {
                      "title": "Enterprise Rent-A-Car",
                      "ads": false,
                      "thumbnail": false,
                      "extensions": [
                        "Car rental agency",
                        "Metairie, LA",
                        "(504) 457-0180",
                        "Closed",
                        "Opens 7:30 AM"
                      ],
                      "rating": "4.2",
                      "review": "194",
                      "pricing": null,
                      "wrapped": "Cannot recommend highly enough.",
                      "options": null,
                      "position": 1
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }
}
```

--------------------------------

### SERP Parsing Task Initialization Response (JSON)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/139902435d58c-serp-scraper-api

Example response after submitting a SERP parsing task. It includes the `task_id` for tracking the task and an array of `blocked_keywords` if any keywords did not meet validation criteria. Blocked keywords are not processed or charged.

```json
{
  "id": "123",
  "result": {
    "task_id": "5492895",
    "blocked_keywords": [
      "*****"
    ]
  }
}
```

--------------------------------

### GET /api/balance

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/139902435d58c-serp-scraper-api

Retrieves your current account balance in USD and the cost for parsing one SERP and keyword volume.

```APIDOC
## GET /api/balance

### Description
This endpoint allows you to check your available balance in USD and the current price for a single SERP parsing operation and keyword volume parsing.

### Method
GET

### Endpoint
/api/balance

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **available_usd** (string) - Your current balance in USD.
- **serp_parsing_cost** (string) - The cost for one SERP parsing operation.
- **volume_parsing_cost** (string) - The cost for one keyword volume parsing operation.

#### Response Example
```json
{
  "id": "123",
  "result": {
    "available_usd": "99999.891",
    "serp_parsing_cost": "0.0004",
    "volume_parsing_cost": "0.0006"
  }
}
```
```

--------------------------------

### Add Keyword List - POST /rt/api/v2

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/9elengxj24hwb-add-keyword-list

The `tasks.addKeywordList` method allows sending keywords to crawl regular SERP and local results. This API has separate billing, and credits must be purchased separately. AI Overview results are currently available at no additional cost for standard Desktop SERP Crawling requests, but will become a separate optional parameter with additional pricing starting August 1, 2025. A new optional parameter `pages` allows parsing multiple SERP pages (1-10) starting September 25, 2025, with costs multiplied by the number of pages requested.

```APIDOC
## POST /rt/api/v2/#tasks.addKeywordList

### Description
Allows sending keywords with commas to crawl regular SERP and local results as an array. Note that this API has separate billing, and credits must be purchased separately. AI Overview results are available at no extra cost for standard Desktop SERP Crawling requests, but will incur additional charges starting August 1, 2025. The `pages` parameter (1-10) can be used to parse multiple SERP pages starting September 25, 2025, with costs multiplied by the number of pages requested.

### Method
POST

### Endpoint
`https://serpstat.com/rt/api/v2/`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **token** (string) - Required - Your API token.

#### Request Body
- **id** (string) - Required - The request identifier provided by the client. It will be echoed as field `id` in the response.
- **method** (string) - Required - Should be exact `tasks.addKeywordList`.
- **params** (object) - Required
  - **keywords** (array[string]) - Required - Keywords with commas for parsing.
  - **seId** (any) - Required - Search engine identifier. Allowed value: 1.
  - **countryId** (integer) - Required - Country identifier. Must be >= 1 and <= 247.
  - **regionId** (integer) - Optional - Region or city identifier. Must be >= 1.
  - **langId** (integer) - Optional - Language identifier. Must be >= 1 and <= 48. Default: 1.
  - **typeId** (integer) - Optional - Device type identifier. Must be >= 1 and <= 2. Default: 1.
  - **type** (string) - Optional - Type of Google results and SERP parsing mode. Allowed values: `regular`, `local`, `regular_aio`. Default: `regular`.
  - **pages** (integer) - Optional - Number of SERP pages to parse (1-10). The cost is multiplied by this value. Default: 1.

### Request Example
```json
{
  "id": "123",
  "method": "tasks.addKeywordList",
  "params": {
    "keywords": [
      "samsung, iphone",
      "nike, adidas"
    ],
    "typeId": 1,
    "seId": 1,
    "countryId": 23,
    "regionId": 21176,
    "langId": 1,
    "pages": 1
  }
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - Required - The request identifier provided by the client. It will be echoed as field `id` in the response.
- **result** (object) - Required
  - **task_id** (string) - Required - Crawling identifier.
  - **blocked_keywords** (array[object]) - Required - Keywords with special symbols, which were rejected, credits won’t be charged.

#### Response Example
```json
{
  "id": "123",
  "result": {
    "task_id": "5484945",
    "blocked_keywords": []
  }
}
```
```

--------------------------------

### Start a New Site Audit

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

Initiates a new site audit for a specified project ID. This action requires confirmation and should be followed by monitoring the audit's progress using 'get_site_audits_list'. Be aware of potential API credit usage.

```json
{
  "tool_code": [
    {
      "name": "start_site_audit",
      "params": {
        "projectId": 123
      }
    }
  ]
}
```

--------------------------------

### Set Serpstat API Token Environment Variable

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

This example demonstrates how to set the Serpstat API token as an environment variable. This is a crucial step for the MCP server to authenticate with the Serpstat API. Ensure the token is kept secure and not committed to version control.

```shell
SERPSTAT_API_TOKEN=your_token_here
```

--------------------------------

### Get Competitor Backlink Summary

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

Analyzes backlinks for a given domain and provides a summary including overall stats, top anchors, and referring domains. Requires the 'get_backlinks_summary', 'get_top10_anchors', and 'get_referring_domains' tools.

```json
{
  "tool_code": [
    {
      "name": "get_backlinks_summary",
      "params": {
        "query": "runningwarehouse.com",
        "searchType": "domain"
      }
    },
    {
      "name": "get_top10_anchors",
      "params": {
        "query": "runningwarehouse.com",
        "searchType": "domain"
      }
    },
    {
      "name": "get_referring_domains",
      "params": {
        "query": "runningwarehouse.com",
        "searchType": "domain",
        "size": 10,
        "sort": "domain_rank",
        "order": "desc"
      }
    }
  ]
}
```

--------------------------------

### API Task Status Check Example

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/139902435d58c-serp-scraper-api

Demonstrates the expected JSON response when a SERP parsing task is not yet complete. It shows the 'progress' and 'message' fields indicating that tracking is ongoing.

```json
{
  "id": "123",
  "result": {
    "progress": "0%",
    "message": "Not all keywords have been tracked"
  }
}
```

--------------------------------

### Keyword Research - Keyword Suggestions

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

Get keyword suggestions for a seed keyword, including search intent, with options for country, filtering, sorting, and limiting results. Provides insights on quick-win and high-volume keywords.

```APIDOC
## GET /keywords/suggestions

### Description
Retrieves keyword suggestions based on a seed keyword, including information about search intent. Supports specifying the search engine, country, filters, sorting, and the number of results.

### Method
GET

### Endpoint
/keywords/suggestions

### Parameters
#### Query Parameters
- **keyword** (string) - Required - The seed keyword for which to get suggestions.
- **se** (string) - Required - The search engine and country code (e.g., 'g_us' for Google US).
- **withIntents** (boolean) - Optional - Whether to include search intent information in the results. Defaults to false.
- **size** (integer) - Optional - The maximum number of suggestions to return.
- **sort.region_queries_count** (string) - Optional - The sorting order for search volume ('asc' or 'desc'). Defaults to 'desc'.
- **filters.keyword_not_contain_one_of** (array of strings) - Optional - A list of keywords to exclude from the suggestions.

### Request Example
```json
{
  "keyword": "best trail running shoes",
  "se": "g_us",
  "withIntents": true,
  "size": 30,
  "sort": {
    "region_queries_count": "desc"
  },
  "filters": {
    "keyword_not_contain_one_of": ["hiking boots", "road shoes", "football"]
  }
}
```

### Response
#### Success Response (200)
- **keyword** (string) - The suggested keyword.
- **region_queries_count** (integer) - The search volume for the keyword.
- **difficulty** (integer) - The SEO difficulty score.
- **cost** (float) - The cost per click (CPC).
- **intents** (string) - The detected search intent (if `withIntents` is true).

#### Response Example
```json
[
  {
    "keyword": "best trail running shoes for women",
    "region_queries_count": 5000,
    "difficulty": 55,
    "cost": 1.10,
    "intents": "informational"
  },
  {
    "keyword": "trail running shoes review",
    "region_queries_count": 3000,
    "difficulty": 50,
    "cost": 0.80,
    "intents": "informational"
  }
]
```
```

--------------------------------

### SERP Crawling API Response Example

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/9elengxj24hwb-add-keyword-list

This JSON object represents a successful response from the `tasks.addKeywordList` API method. It includes the request ID and a `task_id` for tracking the crawling job, along with an empty array for `blocked_keywords` if none were encountered.

```json
{
  "id": "123",
  "result": {
    "task_id": "5484945",
    "blocked_keywords": []
  }
}
```

--------------------------------

### Get Raw SERP

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/139902435d58c-serp-scraper-api

The `getKeywordSerp` method returns the raw SERP in HTML format. To get results, you must use the `keyword_id` parameter from the `getTaskResult` method's response instead of the keyword itself.

```APIDOC
## GET /serp/{keywordId}

### Description
Retrieves the raw SERP HTML content for a given keyword ID.

### Method
GET

### Endpoint
/serp/{keywordId}

### Parameters
#### Path Parameters
- **keywordId** (string) - Required - The ID of the keyword for which to retrieve the raw SERP.

### Request Example
```json
{
  "example": "Not applicable for GET request"
}
```

### Response
#### Success Response (200)
- **html** (string) - The raw HTML content of the SERP page.

#### Response Example
```json
{
  "html": "<!DOCTYPE html><html><head>...</head><body>...</body></html>"
}
```
```

--------------------------------

### Get Parsing Balance - Request Body (JSON)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/hx1b8q97pwu9y-get-parsing-balance

The request body for the `tasks.getParsingBalance` method requires a JSON object with 'id' and 'method' fields. 'id' is a client-provided identifier, and 'method' must be set to 'tasks.getParsingBalance'.

```json
{
  "id": "123",
  "method": "tasks.getParsingBalance"
}
```

--------------------------------

### Get Parsing Balance - cURL Request

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/hx1b8q97pwu9y-get-parsing-balance

This cURL command demonstrates how to make a POST request to the Serpstat API to retrieve the parsing balance. It includes the API token, content type, and the JSON request body.

```curl
curl --request POST \
  --url 'https://serpstat.com/rt/api/v2/?token=123#tasks.getParsingBalance' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ \
  "id": "123", \
  "method": "tasks.getParsingBalance" \
}'
```

--------------------------------

### Initialize SERP Parsing Task

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/139902435d58c-serp-scraper-api

Submit a request to analyze a set of keywords for a specific search region. Use `addTask` for single or few keywords, and `addKeywordList` for up to 10,000 keywords. Both methods support parsing multiple SERP pages.

```APIDOC
## POST /api/serp/tasks

### Description
Initializes a SERP parsing task by submitting keywords, search region specifics, and optional parameters like multiple page parsing.

### Method
POST

### Endpoint
/api/serp/tasks

### Parameters
#### Request Body
- **keywords** (string) - Required - Comma-separated list of keywords to parse.
- **typeId** (integer) - Required - The type of search engine.
- **seId** (integer) - Required - The search engine ID.
- **countryId** (integer) - Required - The country ID for the search region.
- **regionId** (integer) - Required - The region ID for the search region.
- **langId** (integer) - Required - The language ID for the search region.
- **pages** (integer) - Optional - The number of SERP pages to parse (1-10). Multiplies cost.

### Request Example
```json
{
  "id": "123",
  "method": "tasks.addTask",
  "params": {
    "keywords": "iphone 16, samsung galaxy, google pixel",
    "typeId": 1,
    "seId": 1,
    "countryId": 23,
    "regionId": 21176,
    "langId": 1,
    "pages": 3
  }
}
```

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the submitted task.
- **blocked_keywords** (array) - A list of keywords that were blocked due to validation rules.

#### Response Example
```json
{
  "id": "123",
  "result": {
    "task_id": "5492895",
    "blocked_keywords": [
      "*****"
    ]
  }
}
```
```

--------------------------------

### Project Management API v4 - Methods

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/fan1bd16rencj-serpstat-project-management-api-v4

Information on available methods for interacting with projects via the Serpstat Project Management API v4.

```APIDOC
## Project Management API v4 Methods

### Create Project

#### Description
Creates a new project for your Serpstat account.

#### Method
POST

#### Endpoint
`/`

#### Parameters
##### Request Body
- **method** (string) - Required - The API method name, `"project.add"`.
- **token** (string) - Required - Your API key.
- **project_name** (string) - Required - The name for the new project.
- **project_domain** (string) - Required - The domain for the project.

#### Request Example
```json
{
  "method": "project.add",
  "token": "YOUR_API_KEY",
  "project_name": "My New Project",
  "project_domain": "example.com"
}
```

#### Response Example (Success)
```json
{
  "result": {
    "project_id": 12345,
    "project_name": "My New Project",
    "project_domain": "example.com"
  }
}
```

### Get Projects List

#### Description
Retrieves a list of all your projects.

#### Method
POST

#### Endpoint
`/`

#### Parameters
##### Request Body
- **method** (string) - Required - The API method name, `"project.list"`.
- **token** (string) - Required - Your API key.
- **size** (integer) - Optional - Number of results per page.
- **page** (integer) - Optional - Page number.

#### Request Example
```json
{
  "method": "project.list",
  "token": "YOUR_API_KEY",
  "size": 50,
  "page": 1
}
```

#### Response Example (Success)
```json
{
  "result": [
    {
      "project_id": 12345,
      "project_name": "My Project 1",
      "project_domain": "example.com"
    },
    {
      "project_id": 67890,
      "project_name": "My Project 2",
      "project_domain": "anotherdomain.org"
    }
  ],
  "total_results": 100
}
```

### Delete Project

#### Description
Deletes a specific project from your Serpstat account.

#### Method
POST

#### Endpoint
`/`

#### Parameters
##### Request Body
- **method** (string) - Required - The API method name, `"project.delete"`.
- **token** (string) - Required - Your API key.
- **project_id** (integer) - Required - The ID of the project to delete.

#### Request Example
```json
{
  "method": "project.delete",
  "token": "YOUR_API_KEY",
  "project_id": 12345
}
```

#### Response Example (Success)
```json
{
  "result": {
    "status": "success",
    "message": "Project with ID 12345 deleted successfully."
  }
}
```
```

--------------------------------

### Filters

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/0b54hq7qrsbab-serpstat-serp-crawling-api

Explanation of how to apply filters to API requests.

```APIDOC
## Filters

### Description
Filters can be applied to each method, most of them are specific for the method you used. `filters` object are optional for most methods.
```

--------------------------------

### Get Parsing Balance - Response (JSON)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/hx1b8q97pwu9y-get-parsing-balance

A successful response (200 OK) for the `tasks.getParsingBalance` method returns a JSON object containing the request 'id' and a 'result' object. The 'result' object details the 'available_usd' balance, 'serp_parsing_cost', and 'volume_parsing_cost'.

```json
{
  "id": "123",
  "result": {
    "available_usd": "99999.891",
    "serp_parsing_cost": "0.0004",
    "volume_parsing_cost": "0.0006"
  }
}
```

--------------------------------

### Get Task Status API Request Body (JSON)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/ysi42jt8k737w-get-task-status

This is the JSON payload required to initiate a request to the SerpstatTaskProcedure.getTaskStatus method. It includes a unique client-provided ID, the method name, and a params object containing the taskId for the desired operation.

```json
{
  "id": "123",
  "method": "SerpstatTaskProcedure.getTaskStatus",
  "params": {
    "taskId": "aa28e2a5-a81c-43c9-b441-50d82e8e182e"
  }
}
```

--------------------------------

### Get Task Status API Response (JSON)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/ysi42jt8k737w-get-task-status

This JSON structure represents a successful response from the SerpstatTaskProcedure.getTaskStatus method. It includes the original request ID and a result object detailing the total keywords, a breakdown of keyword statuses, and the overall task progress percentage.

```json
{
  "id": "123",
  "result": {
    "totalKeywords": 6,
    "keywordsStatusCount": [
      {
        "status": 2,
        "count": 6
      }
    ],
    "progress": 100
  }
}
```

--------------------------------

### Get Detailed Site Audit Errors

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

Retrieves detailed information about specific errors found in a site audit, such as pages missing meta descriptions. This involves multiple steps: getting the latest report ID, then fetching detailed reports and specific errors using 'get_site_audits_list' and 'get_site_audit_pages_spec_errors'.

```json
{
  "tool_code": [
    {
      "name": "get_site_audits_list",
      "params": {
        "projectId": 123
      }
    }
  ]
}
{
  "tool_code": [
    {
      "name": "get_site_audit_detailed_report",
      "params": {
        "reportId": "<reportId>"
      }
    }
  ]
}
{
  "tool_code": [
    {
      "name": "get_site_audit_pages_spec_errors",
      "params": {
        "projectId": 123,
        "reportId": "<reportId>",
        "compareReportId": "<reportId>",
        "errorName": "no_desc",
        "limit": 100
      }
    }
  ]
}
```

--------------------------------

### Project Management API v4 - Overview

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/fan1bd16rencj-serpstat-project-management-api-v4

Details about the Serpstat Project Management API v4, including base URL, authentication, request format, and response structure.

```APIDOC
## Serpstat Project Management API v4

### Description
Manage your Serpstat projects with the Project Management API v4. This API allows you to create, delete, and retrieve a list of your projects.

### Base URL
`https://api.serpstat.com/v4`

### Authentication
API requests must include an `token` query parameter for authentication.
Example: `?token=YOUR_API_KEY`

### Request Format
- **Method**: POST
- **Body**: JSON format
- **Required Parameter**: `method` (case-sensitive name of the API method)

### Response Format
- **Format**: JSON
- **Status**: All responses return a 200 HTTP status, even in case of errors. Errors are indicated by an `error` object in the response payload.

### Pagination
- `size` (integer): Number of results per page (default: 100, maximum: 1000).
- `page` (integer): Page number (default: 1).
Note: Not all methods support pagination.

### Filters
- `filters` (object): Optional object for applying method-specific filters.
```

--------------------------------

### Get Task Status using Serpstat API (Shell/cURL)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/ysi42jt8k737w-get-task-status

This snippet demonstrates how to call the SerpstatTaskProcedure.getTaskStatus method using cURL. It requires your API token and the taskId of the task you want to check. The request body specifies the method and parameters, and the response provides the task's progress and keyword status.

```curl
curl --request POST \
  --url 'https://api.serpstat.com/v4/?token=123#SerpstatTaskProcedure.getTaskStatus' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ \
  "id": "123", \
  "method": "SerpstatTaskProcedure.getTaskStatus", \
  "params": { \
    "taskId": "aa28e2a5-a81c-43c9-b441-50d82e8e182e" \
  } \
}'
```

--------------------------------

### API Protocol and Request Format

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/8qvah42r5f9la-keyword-analysis-api

Understand the API protocol and the required format for making requests.

```APIDOC
### API Protocol and Request Format

- **Protocol**: The API uses **JSON-RPC 2.0**.
- **Method**: All requests must be sent using the **POST** method.
- **Request Body**: All parameters must be sent in the request body in **JSON** format.
- **`method` Parameter**: Each request must include a `method` parameter specifying the API method to call (case-sensitive).

**Example Request Body Structure:**
```json
{
  "method": "methodName.specificAction",
  "params": { ... parameters ... },
  "token": "YOUR_API_TOKEN"
}
```
```

--------------------------------

### Credits API

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/25i6hwpyk7drz-credits-api

Monitor your API credit usage with the Credits API. Get up-to-date information on your current balance and consumption to effectively manage your subscription limits.

```APIDOC
## GET /credits

### Description
Retrieves the current API credit balance and usage information.

### Method
POST

### Endpoint
https://api.serpstat.com/v4

### Parameters
#### Query Parameters
- **token** (string) - Required - Your API authentication token.

#### Request Body
- **method** (string) - Required - The API method to call, which is `credits` for this endpoint.
- **id** (integer) - Optional - A unique identifier for the request.
- **params** (object) - Optional - An object containing additional parameters for the method.
  - **size** (integer) - Optional - Number of results per page (default 100, maximum 1000).
  - **page** (integer) - Optional - Page number (default is 1st page).

### Request Example
```json
{
  "method": "credits",
  "token": "YOUR_API_TOKEN",
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the credit information.
  - **credits_balance** (integer) - The remaining API credit balance.
  - **credits_consumption** (integer) - The total API credits consumed.
- **id** (integer) - The ID of the request.

#### Error Response (200)
- **error** (object) - Contains error details.
  - **code** (integer) - The error code.
  - **message** (string) - A description of the error.

#### Response Example
```json
{
  "result": {
    "credits_balance": 10000,
    "credits_consumption": 500
  },
  "id": 1
}
```
```

--------------------------------

### API Credits and Rate Limits

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/8qvah42r5f9la-keyword-analysis-api

Understand API credit usage, request limits, and rate restrictions.

```APIDOC
### API Credits and Rate Limits

- **API Credits**: Your pricing plan's API requests are counted towards your credit usage, including identical and export requests.
- **Request Rates**: Most subscription plans are limited to 1 request per second. Top-tier plans allow up to 10 requests per second. Contact sales for higher rate limits. Exceeding limits will result in an error response.
- **Max Results**: The maximum number of results returned by each API method is limited to 60,000 rows.
```

--------------------------------

### Submit Serpstat API Request (cURL)

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/v91plc4ro30g6-get-task-result

This snippet shows how to make a POST request to the Serpstat API using cURL. It includes the API endpoint, necessary headers (Accept and Content-Type), and the JSON payload containing the request details. This is useful for testing API interactions from the command line.

```shell
curl --request POST \
  --url 'https://api.serpstat.com/v4/?token=123#SerpstatTaskProcedure.getTaskResult' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{ \
  "id": "123", \
  "method": "SerpstatTaskProcedure.getTaskResult", \
  "params": { \
    "taskId": "aa28e2a5-a81c-43c9-b441-50d82e8e182e", \
    "page": 1, \
    "pageSize": 10 \
  } \
}'
```

--------------------------------

### Site Audit Endpoints

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/mg8k21wk8yjxp-serpstat-mcp-server

Manage and retrieve data from site audits, including detailed error reports and starting new audits.

```APIDOC
## Site Audit

### Prompt 13 — Detailed Errors (drill-down example)

**Description**: Shows detailed information for specific errors found during a site audit, such as pages missing meta descriptions.

**Steps**:
1. `get_site_audits_list`: Retrieve the latest `reportId` for a given `projectId`.
2. `get_site_audit_detailed_report`: Use the `reportId` from step 1 to get detailed audit data.
3. Identify the error key for the specific issue (e.g., "no_desc" for missing meta descriptions).
4. `get_site_audit_pages_spec_errors`:
   - `projectId`: The project ID (e.g., 123).
   - `reportId`: The report ID.
   - `compareReportId`: The report ID for comparison (can be the same for baseline).
   - `errorName`: The specific error to query (e.g., "no_desc").
   - `limit`: Maximum number of results (e.g., 100).

**Output Format**:
- Table: `url` (or `urlCrc` reference), `occurrences`.
- Notes limitations for page-level errors if CRC is required.

### Prompt 14 — Start a New Audit

**Description**: Initiates a new site audit for a specified project. Confirmation is required before execution.

**Tool and Parameters**:
- `start_site_audit`:
  - `projectId`: The project ID (e.g., 123).

**Monitoring**:
- Progress can be monitored using `get_site_audits_list` until `progress` reaches 100.
- Avoid requesting detailed results before the audit is complete.
- Warn about API credit usage per page.
```

--------------------------------

### SerpstatTaskProcedure.getTaskStatus

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/ysi42jt8k737w-get-task-status

The `SerpstatTaskProcedure.getTaskStatus` method allows you to obtain the status of a position check using a `taskId`. This method does not consume API credits.

```APIDOC
## POST /v4/

### Description
Retrieves the status of a task using its `taskId`. This method is useful for tracking the progress of keyword position checks initiated via `SerpstatTaskProcedure.addKeywordListFreq`.

### Method
POST

### Endpoint
`https://api.serpstat.com/v4/`

### Parameters
#### Query Parameters
- **token** (string) - Required - Your Serpstat API key.

#### Request Body
- **id** (string) - Required - A unique identifier for the request, which will be echoed in the response.
- **method** (string) - Required - Must be set to `"SerpstatTaskProcedure.getTaskStatus"`.
- **params** (object) - Required - An object containing parameters for the method.
  - **taskId** (string) - Required - The ID of the task for which to retrieve the status. This ID is typically obtained when adding a keyword list for analysis.

### Request Example
```json
{
  "id": "123",
  "method": "SerpstatTaskProcedure.getTaskStatus",
  "params": {
    "taskId": "aa28e2a5-a81c-43c9-b441-50d82e8e182e"
  }
}
```

### Request Example (cURL)
```bash
curl --request POST \
  --url 'https://api.serpstat.com/v4/?token=YOUR_API_TOKEN#SerpstatTaskProcedure.getTaskStatus' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "123",
  "method": "SerpstatTaskProcedure.getTaskStatus",
  "params": {
    "taskId": "aa28e2a5-a81c-43c9-b441-50d82e8e182e"
  }
}'
```

### Response
#### Success Response (200 OK)
- **id** (string) - The request identifier provided by the client.
- **result** (object) - An object containing the task status details.
  - **totalKeywords** (integer) - The total number of keywords associated with the task.
  - **keywordsStatusCount** (array[object]) - An array detailing the count of keywords by status.
    - **status** (integer) - The status code of the keywords (e.g., 2 for processed).
    - **count** (integer) - The number of keywords with the specified status.
  - **progress** (integer) - The completion percentage of the task.

#### Response Example
```json
{
  "id": "123",
  "result": {
    "totalKeywords": 6,
    "keywordsStatusCount": [
      {
        "status": 2,
        "count": 6
      }
    ],
    "progress": 100
  }
}
```
```

--------------------------------

### Project Management API

Source: https://api-docs.serpstat.com/docs/serpstat-public-api/eulycl3dnfrz8-team-management-api

APIs for managing projects within Serpstat.

```APIDOC
## Project Management API

### Description
APIs for managing projects within Serpstat.

### Method
POST

### Endpoint
https://api.serpstat.com/v4

### Parameters
#### Query Parameters
- **token** (string) - Required - Your API key for authentication.

#### Request Body
- **method** (string) - Required - The name of the API method to call (e.g., `projects.get_list`).
- **params** (object) - Optional - Parameters specific to the method being called.

### Request Example
```json
{
  "method": "projects.get_list",
  "params": {
    "token": "YOUR_API_TOKEN"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the API method's result data.
- **error** (object) - Contains error details if the request failed.

#### Response Example
```json
{
  "result": {
    "projects": [
      {
        "id": 456,
        "name": "My Project"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": null
}
```
```