## SERP Analyzer

### GET /api/v1/exports/csv/serp_analyzer
List SERP Analyzer queries for a workspace
Returns a list of SERP Analyzer queries for a workspace in the CSV format.
Up to 5000 entries from the last month.
It uses workspace ID from the `Workspace-Id` header.
If the `Workspace-Id` header is not provided, uses the oldest active workspace for the user's owned organization.

**Rate limit**: 10 requests/sec

Example response:

```
"id","state","created","location","keyword"
"2871118","scheduled","2023-07-31 22:03:52Z","United States","how to build gaming pc"
"2800997","completed","2023-07-12 13:53:37Z","United States","rustic wedding ideas"
"2796112","completed","2023-07-11 10:53:21Z","United States","seo keyword"
```

**Parameters**

- `Workspace-Id` (header, integer) — Workspace ID to list SERP Analyzer queries from. If not provided, uses the oldest active workspace.

**Responses**

- **200** — 
- **429** — Rate limit exceeded


### GET /api/v1/exports/csv/serp_analyzer/{serp_analyzer_id}/prominent_terms
Get prominent terms
Returns prominent words and phrases for a given query.
The report includes word/phrase counts and their density.

**Rate limit**: 10 requests/sec

Example response:
```
"term","pages","density_min","density_avg","density_max","words_min","words_avg","words_max"
"pc builds","4","0.0","0.0","0.0","4.0","4.0","4.0"
"pcie slot","4","0.0","0.0","0.0","5.0","5.0","5.0"
"gaming performance","5","0.0","0.0","0.0","2.0","4.17","12.0"
"best gaming","4","0.0","0.0","0.0","2.0","4.4","9.0"
"graphics card","8","0.0","0.0","0.0","5.0","10.11","16.0"
"graphics cards","6","0.0","0.0","0.0","2.0","2.0","2.0"
"gaming pc","10","0.0","0.0","0.01","2.0","10.88","53.0"
"air cooler","4","0.0","0.0","0.0","2.0","2.0","2.0"
"pc build","7","0.0","0.0","0.01","2.0","5.88","19.0"
```

The exact number of keywords varies depending on the specified keyword and content from Google.
Prominent words are only populated if your selected country for the query does not support NLP analysis. With NLP on - prominent words are automatically assembled into phrases.

Response can only be generated after SERP Analyzer query finishes loading and state is reported as `completed`.

**Parameters**

- `serp_analyzer_id` (path, integer, required)

**Responses**

- **200** — 
- **404** — Not found
- **429** — Rate limit exceeded


### GET /api/v1/exports/csv/serp_analyzer/{serp_analyzer_id}/search_results
Get search results
Returns search results for a given query in the CSV format. The report contains URLs with SERP data, keywords and factors calculated by Surfer.
The data here highlights important page characteristics and provides high-level overview of SERP quality.

**Rate limit**: 10 requests/sec

Example response:

```
"position","url","state","title/keywordCount/all","title/keywordCount/outsideLinks","meta_description/keywordCount/all","meta_description/keywordCount/outsideLinks","url/path/keywordCount/all","url/domain/keywordCount/all","body/wordCount/all","body/wordCount/outsideLinks","body/keywordCount/all","body/keywordCount/outsideLinks","p/wordCount/all","p/wordCount/outsideLinks","p/keywordCount/all","p/keywordCount/outsideLinks","p/elementCount/all","p/elementCount/outsideLinks","headings/wordCount/all","headings/wordCount/outsideLinks","headings/keywordCount/all","headings/keywordCount/outsideLinks","headings/elementCount/all","headings/elementCount/outsideLinks","above_the_fold/wordCount/all","above_the_fold/wordCount/outsideLinks","above_the_fold/keywordCount/all","above_the_fold/keywordCount/outsideLinks","h1/keywordCount/all","h1/keywordCount/outsideLinks","h2/keywordCount/all","h2/keywordCount/outsideLinks","h3/keywordCount/all","h3/keywordCount/outsideLinks","h4/keywordCount/all","h4/keywordCount/outsideLinks","h5/keywordCount/all","h5/keywordCount/outsideLinks","h6/keywordCount/all","h6/keywordCount/outsideLinks","h1/elementCount/all","h1/elementCount/outsideLinks","h2/elementCount/all","h2/elementCount/outsideLinks","h3/elementCount/all","h3/elementCount/outsideLinks","h4/elementCount/all","h4/elementCount/outsideLinks","h5/elementCount/all","h5/elementCount/outsideLinks","h6/elementCount/all","h6/elementCount/outsideLinks","img_alt/keywordCount/all","img_alt/keywordCount/outsideLinks","img_alt/wordCount/all","img_alt/wordCount/outsideLinks","img/elementCount/all","img/elementCount/outsideLinks","strong_and_b/wordCount/all","strong_and_b/wordCount/outsideLinks","strong_and_b/keywordCount/all","strong_and_b/keywordCount/outsideLinks","strong_and_b/elementCount/all","strong_and_b/elementCount/outsideLinks","score/content/all","pageSpeed/ttfb/all","pageSpeed/totalSize/all","pageSpeed/load/all"
"1","https://www.intel.com/content/www/us/en/gaming/resources/how-to-build-a-gaming-pc.html","completed","0","0","0","0","1","0","8251","7087","0","0","5022","4885","0","0","134","134","214","139","0","0","34","34","81","68","0","0","0","0","0","0","0","0","0","0","0","0","0","0","1","1","18","18","14","14","2","2","0","0","0","0","0","0","215","205","40","38","108","92","0","0","37","37","77","99","4139.0771484375","11186"
```

The exact amount of SERP results may vary depending on the specified keyword, location and device type, max top 50 competitors.

Each row can be considered a "mini-query" with it's own `state`, which can be:

- `scheduled` - crawl and analysis of this specific competitor did not complete yet

- `failed` - crawl did not succeed, most likely due to timeout, bot block or content paint issue

- `completed` - crawl completed and populated data fields based on received HTML code

**Parameters**

- `serp_analyzer_id` (path, integer, required)

**Responses**

- **200** — 
- **404** — Not found
- **429** — Rate limit exceeded


### POST /api/v1/serp_analyzer
Create SERP Analyzer query
**Deprecated.**
**Deprecated:** Use `/api/v1/serp_analyzers` instead.

**Rate limits**:
- 10 requests/sec
- each query created will count against your daily limit. [Fair Use Policy applies](https://docs.surferseo.com/en/articles/12944161-fair-usage-policy), by default 100 queries a day.

**Parameters**

- `Workspace-Id` (header, integer) — Workspace ID to create the query in. If not provided, uses the oldest active workspace.

**Request body**

```json
{
  "device": "mobile",
  "location": "United States",
  "keyword": "How to write content that ranks?",
  "analyze_nlp_entity_sentiment": false,
  "screenshot": false,
  "analyze_nlp_sentiment": false
}
```

**Responses**

- **201** — 
```json
{
  "id": 123,
  "state": "scheduled"
}
```
- **422** — Quota exceeded | No access
- **429** — Rate limit exceeded


### POST /api/v1/serp_analyzer/batches
Create a batch of SERP Analyzer queries
**Deprecated.**
**Deprecated:** Use `/api/v1/serp_analyzers/batch` instead.

**Rate limits**:
- 10 requests/min
- each query created will count against your daily limit. [Fair Use Policy applies](https://docs.surferseo.com/en/articles/12944161-fair-usage-policy), by default 100 queries a day.

**Parameters**

- `Workspace-Id` (header, integer) — Workspace ID to create the queries in. If not provided, uses the oldest active workspace.

**Request body**

```json
[
  {
    "keyword": "SEO"
  },
  {
    "keyword": "SurferSEO"
  }
]
```

**Responses**

- **201** — 
```json
[
  {
    "id": 1,
    "state": "scheduled"
  },
  {
    "error": "quota_exceeded",
    "input": {
      "keyword": "SurferSEO"
    }
  }
]
```
- **422** — Quota exceeded | No access
- **429** — Rate limit exceeded


### POST /api/v1/serp_analyzers
Create SERP Analyzer query
**Rate limits**:
- 10 requests/sec
- each query created will count against your daily limit. [Fair Use Policy applies](https://docs.surferseo.com/en/articles/12944161-fair-usage-policy), by default 100 queries a day.

**Parameters**

- `Workspace-Id` (header, integer) — Workspace ID to create the query in. If not provided, uses the oldest active workspace.

**Request body**

```json
{
  "device": "mobile",
  "location": "United States",
  "keyword": "How to write content that ranks?",
  "analyze_nlp_entity_sentiment": false,
  "screenshot": false,
  "analyze_nlp_sentiment": false
}
```

**Responses**

- **201** — 
```json
{
  "id": 123,
  "state": "scheduled"
}
```
- **422** — Quota exceeded | No access
- **429** — Rate limit exceeded


### POST /api/v1/serp_analyzers/batch
Create a batch of SERP Analyzer queries
**Rate limits**:
- 10 requests/min
- each query created will count against your daily limit. [Fair Use Policy applies](https://docs.surferseo.com/en/articles/12944161-fair-usage-policy), by default 100 queries a day.

**Parameters**

- `Workspace-Id` (header, integer) — Workspace ID to create the queries in. If not provided, uses the oldest active workspace.

**Request body**

```json
[
  {
    "keyword": "SEO"
  },
  {
    "keyword": "SurferSEO"
  }
]
```

**Responses**

- **201** — 
```json
[
  {
    "id": 1,
    "state": "scheduled"
  },
  {
    "error": "quota_exceeded",
    "input": {
      "keyword": "SurferSEO"
    }
  }
]
```
- **422** — Quota exceeded | No access
- **429** — Rate limit exceeded