MetricSpot SEO API

https://metricspot.com/features/seo-api/
Admin
The MetricSpot SEO API provides on-demand SEO and AI-readability audits for any URL, offering...
Tokens:3,960
Snippets:43
Trust Score:9.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### GET /api/audits/:id/report

Source: https://metricspot.com/features/seo-api

Preview HTML report.

```APIDOC
## GET /api/audits/:id/report

### Description
Render the audit report as branded HTML. Useful for embedding in a client portal iframe.

### Method
GET

### Endpoint
/api/audits/:id/report

### Parameters
#### Path Parameters
- **id** (string) - Required - The audit ID.

#### Query Parameters
- **lang** (string) - Optional - Language code.
- **brand_id** (integer) - Optional - Brand identifier.
```

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

### GET /api/pdfs/:id/download

Source: https://metricspot.com/features/seo-api

Direct download of a completed PDF.

```APIDOC
## GET /api/pdfs/:id/download

### Description
Direct download of a completed PDF with Content-Disposition: attachment.

### Method
GET

### Endpoint
/api/pdfs/:id/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The PDF request ID.
```

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

### GET /api/audits

Source: https://metricspot.com/features/seo-api

List the account's audits.

```APIDOC
## GET /api/audits

### Description
List the account's audits, most recent first, deduplicated by URL. Returns audit_id, url, status, total_score, has_ga, has_gsc, created_at. Default limit 24, max 100.

### Method
GET

### Endpoint
/api/audits
```

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

### GET /api/audits/usage

Source: https://metricspot.com/features/seo-api

Return current month's audit quota.

```APIDOC
## GET /api/audits/usage

### Description
Return current month's audit quota: audits_remaining, audits_used, plan_limit, reset_at.

### Method
GET

### Endpoint
/api/audits/usage
```

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

### GET /api/pdfs/:id

Source: https://metricspot.com/features/seo-api

Poll PDF status.

```APIDOC
## GET /api/pdfs/:id

### Description
Returns { pdf: { id, status, download_url } }. If Accept: application/pdf and status is ready, returns the PDF binary directly.

### Method
GET

### Endpoint
/api/pdfs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The PDF request ID.
```

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

### GET /api/audits/history

Source: https://metricspot.com/features/seo-api

Return up to 50 historical audits for one URL.

```APIDOC
## GET /api/audits/history

### Description
Return up to 50 historical audits for one URL. Useful for tracking score drift over time.

### Method
GET

### Endpoint
/api/audits/history

### Parameters
#### Query Parameters
- **url** (string) - Required - The encoded URL to fetch history for.
```

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

### GET /api/audits/:id

Source: https://metricspot.com/features/seo-api

Fetch a previously queued audit by id.

```APIDOC
## GET /api/audits/:id

### Description
Fetch a previously queued audit by id. Returns the 15 module scores (0-100), the total score, every finding with severity and recommendation text, plus links to the HTML and PDF reports.

### Method
GET

### Endpoint
/api/audits/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the audit.
```

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

### POST /api/public/audit

Source: https://metricspot.com/features/seo-api/reference

Runs a lightweight SEO audit synchronously for a given URL without requiring authentication. This endpoint is rate-limited to 1 request per IP per 24 hours.

```APIDOC
## POST /api/public/audit

### Description
Runs a lightweight SEO audit synchronously and returns the result in the response body. Does not persist a normal audit record and skips Core Web Vitals (PageSpeed Insights).

### Method
POST

### Endpoint
https://app.metricspot.com/api/public/audit

### Parameters
#### Request Body
- **url** (string) - Required - The URL to audit (max length 2000, format: uri).

### Request Example
{
  "url": "https://example.com"
}

### Response
#### Success Response (200)
- **audit** (object) - The audit results including scores and rules.
- **note** (string) - Informational note regarding anonymous audit limitations.

#### Response Example
{
  "audit": {
    "url": "https://example.com",
    "domain": "example.com",
    "total_score": 72,
    "module_scores": {
      "meta": 90,
      "headings": 70,
      "links": 65,
      "images": 80,
      "performance": 0,
      "structured_data": 60,
      "accessibility": 75,
      "security": 100,
      "crawlability": 80,
      "content": 55,
      "organic_traffic": 100
    },
    "rules": [
      {
        "module": "meta",
        "rule_id": "title_present",
        "passed": true,
        "severity": "minor",
        "title": "Page title is present",
        "recommendation": null,
        "data": {}
      }
    ]
  },
  "note": "Anonymous audits are limited and do not include Core Web Vitals. Sign up free for full audits and PDF reports."
}
```

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

### POST /api/audits

Source: https://metricspot.com/features/seo-api

Queue a full SEO and AI-readability audit.

```APIDOC
## POST /api/audits

### Description
Queue a full SEO and AI-readability audit. Includes Core Web Vitals from Google PageSpeed Insights, and organic traffic if GA4 and Google Search Console are linked. Responds immediately with audit_id and status: queued.

### Method
POST

### Endpoint
/api/audits
```

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

### Run an anonymous SEO audit

Source: https://metricspot.com/features/seo-api/reference

Executes a lightweight SEO audit synchronously without requiring authentication. This endpoint is rate-limited to one request per IP address every 24 hours.

```shell
curl https://app.metricspot.com/api/public/audit \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com"
}'
```

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

### Perform an authenticated SEO audit

Source: https://metricspot.com/features/seo-api

Execute an audit using a Bearer token. Requires a Pro plan and counts against the monthly quota.

```javascript
const res = await fetch("https://app.metricspot.com/api/audits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ms_live_xxx",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});
const audit = await res.json();
```

```python
import httpx

res = httpx.post(
    "https://app.metricspot.com/api/audits",
    headers={"Authorization": "Bearer ms_live_xxx"},
    json={"url": "https://example.com"},
)
audit = res.json()
```

```php
<?php
$ch = curl_init("https://app.metricspot.com/api/audits");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer ms_live_xxx",
  ],
  CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com"]),
  CURLOPT_RETURNTRANSFER => true,
]);
$audit = json_decode(curl_exec($ch), true);
```

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

### POST /api/audits/:id/pdf

Source: https://metricspot.com/features/seo-api

Kick off a branded PDF render for a completed audit.

```APIDOC
## POST /api/audits/:id/pdf

### Description
Kick off a branded PDF render for a completed audit. Returns 201 with { pdf: { id, status: "pending" } }.

### Method
POST

### Endpoint
/api/audits/:id/pdf

### Parameters
#### Path Parameters
- **id** (string) - Required - The audit ID.

### Request Body
- **language** (string) - Optional - Language code.
- **brand_id** (integer) - Optional - Brand identifier.
```

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

### Perform an anonymous SEO audit with curl

Source: https://metricspot.com/features/seo-api

Execute a public audit without authentication. This endpoint is rate-limited to one request per IP every 24 hours.

```bash
curl -s -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq .total_score
```

```bash
curl -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
```

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

### POST /api/audits

Source: https://metricspot.com/features/seo-api

Performs an authenticated SEO audit on a specified URL. Requires a valid Bearer token and an active Pro plan.

```APIDOC
## POST /api/audits

### Description
Performs an authenticated SEO audit on a specified URL. Requires a Bearer token in the Authorization header.

### Method
POST

### Endpoint
https://app.metricspot.com/api/audits

### Request Body
- **url** (string) - Required - The URL of the website to audit.

### Request Example
{
  "url": "https://example.com"
}
```

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

### POST /api/public/audit

Source: https://metricspot.com/features/seo-api/reference

Runs an anonymous SEO audit for a specified URL.

```APIDOC
## POST /api/public/audit

### Description
Run an anonymous SEO audit for a given website URL.

### Method
POST

### Endpoint
/api/public/audit

### Request Body
- **url** (string) - Required - The URL of the website to audit.

### Request Example
{
  "url": "https://example.com"
}
```

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

### PATCH /api/audits/reorder

Source: https://metricspot.com/features/seo-api

Set display position of audits in the dashboard.

```APIDOC
## PATCH /api/audits/reorder

### Description
Set display position of audits in the dashboard. Returns 204.

### Method
PATCH

### Endpoint
/api/audits/reorder

### Request Body
- **url_order** (array) - Required - List of URLs in desired order (max 200).
```

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

### Anonymous audit response schema

Source: https://metricspot.com/features/seo-api/reference

The JSON structure returned by the public audit endpoint, containing module-specific scores and rule validation results.

```json
{
  "audit": {
    "url": "https://example.com",
    "domain": "example.com",
    "total_score": 72,
    "module_scores": {
      "meta": 90,
      "headings": 70,
      "links": 65,
      "images": 80,
      "performance": 0,
      "structured_data": 60,
      "accessibility": 75,
      "security": 100,
      "crawlability": 80,
      "content": 55,
      "organic_traffic": 100
    },
    "rules": [
      {
        "module": "meta",
        "rule_id": "title_present",
        "passed": true,
        "severity": "minor",
        "title": "Page title is present",
        "recommendation": null,
        "data": {}
      }
    ]
  },
  "note": "Anonymous audits are limited and do not include Core Web Vitals. Sign up free for full audits and PDF reports."
}
```

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

### DELETE /api/audits/:id

Source: https://metricspot.com/features/seo-api

Delete all audits matching the URL of the given audit_id.

```APIDOC
## DELETE /api/audits/:id

### Description
Delete all audits matching the URL of the given audit_id. Returns 204 on success.

### Method
DELETE

### Endpoint
/api/audits/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the audit.
```
Tokens:
Raw