---
title: "Optimize: score a page"
description: "Score an existing page against its SERP competitors with durable, retry-safe Optimize runs."
canonical_url: "https://developers.rankability.com/guides/optimize"
section: "Guides"
last_updated: 2026-11-14
---

# Optimize: score a page

Score an existing page against its SERP competitors with durable, retry-safe Optimize runs.

## Optimize — Score a page

`POST /api/agent/v1/optimize` (durable Agent contract)

`POST /api/v1/optimize` (synchronous internal admin contract)

Score any public URL against SERP competitors for a given keyword. The customer Agent API creates a durable asynchronous run and returns its ID immediately; the internal admin endpoint continues to execute the underlying scoring pipeline synchronously.

The Agent API run is persisted in the shared asynchronous job store. It does not create a Copywriter project or edit content. Poll or list the saved run, then retrieve its full result after completion.

The durable contract is available at `/api/agent/v1/optimize` and through MCP as `optimize_page`, `optimization_get`, and `optimization_list`. The `/api/v1/optimize` admin-key route is the synchronous internal scoring pipeline used by the background runner.

### Authentication

**Option 1: Bearer token (recommended)**

Use an `rk_live_` API key with the `optimize:run` scope. This is the same auth used by all other Agent API endpoints and by MCP.

```
POST /api/agent/v1/optimize
Authorization: Bearer rk_live_YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: stable-logical-run-key
```

**Option 2: Admin key (legacy)**

Pass the admin key via the `X-Admin-Key` header. This method is supported for backward compatibility.

```
POST /api/v1/optimize
X-Admin-Key: your-admin-key
Content-Type: application/json
```

### Request body

```json
{
  "url": "https://example.com/your-page",
  "keyword": "target keyword",
  "language": "en-US",
  "client_id": "4746d28b-0a38-43f9-a1ca-5e8402ef73d4"
}
```

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string (URL) | Yes | — | The public URL to analyze and score. Must use `http` or `https` protocol. Private/internal hosts (localhost, private IPs, metadata endpoints) are blocked. |
| `keyword` | string | Yes | — | The target keyword to evaluate the page against |
| `language` | string | No | `"en-US"` | Language code for SERP data (e.g., `en-US`, `es`, `de`, `ja`). Max 10 characters. |
| `client_id` | UUID | No | — | Organization-owned client used for run attribution and history filtering. |

### Security

The endpoint includes SSRF protection — URLs pointing to private networks, localhost, link-local addresses (169.254.x.x), or cloud metadata endpoints are rejected with a `400` error.

### Credits

Use `GET /usage` and `GET /usage/estimate?operation=optimize_page` for the active account contract. A caller-supplied `Idempotency-Key` is required. The same key maps to one durable run, one reservation, and at most one provider execution.

If the authenticated user has an organization with insufficient credits, the endpoint returns:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits",
    "details": {
      "credits_required": 400,
      "credits_available": 250
    }
  }
}
```

The numbers above are illustrative. The usage estimate endpoint is authoritative for the authenticated account's active contract.

HTTP status: `402`

### Accepted Agent response (202)

```json
{
  "optimization_id": "opt-0123456789abcdef",
  "status": "queued",
  "url": "https://example.com/your-page",
  "keyword": "target keyword"
}
```

Poll `GET /api/agent/v1/optimizations/:id?view=status`. After `status` becomes `complete`, request `view=full`. The saved `result` contains the scoring payload described below. `GET /api/agent/v1/optimizations` lists compact saved history.

### Full saved result

```json
{
  "url": "https://example.com/your-page",
  "keyword": "target keyword",
  "language": "en-US",
  "entities": [
    {
      "name": "Entity Name",
      "type": "brand",
      "importance": "required",
      "sourceCount": 7
    }
  ],
  "rankabilityScore": 72,
  "categoryScores": {
    "copywriting": 16,
    "readability": 8,
    "seo": 12,
    "structure": 8,
    "coverage": 11,
    "uniqueness": 14,
    "credibility": 7
  },
  "scoreDetails": {
    "categoryBreakdowns": {
      "copywriting": { "score": 16, "maxScore": 20, "issues": [] },
      "readability": { "score": 8, "maxScore": 10, "gradeLevel": 9.2 },
      "seo": { "score": 12, "maxScore": 15, "topicPresence": { "title": true, "firstPara": true } },
      "structure": { "score": 8, "maxScore": 10 },
      "coverage": { "score": 11, "maxScore": 15, "entitiesFound": ["..."], "entitiesMissing": ["..."] },
      "uniqueness": { "score": 14, "maxScore": 20 },
      "credibility": { "score": 7, "maxScore": 10 }
    },
    "totalScore": 72,
    "entityCoverage": { "score": 65, "found": 48, "total": 72, "percentage": 66.7 },
    "scoredAt": "2026-04-08T12:00:00.000Z"
  },
  "sourceWordCount": 2150,
  "competitorCount": 12,
  "competitors": [
    {
      "url": "https://competitor.com/page",
      "title": "Competitor Page Title",
      "source": "organic",
      "wordCount": 3200
    }
  ],
  "duration": 45000
}
```

| Field | Type | Description |
|---|---|---|
| `url` | string | The analyzed URL |
| `keyword` | string | The target keyword |
| `language` | string | Language code used for SERP data |
| `entities` | array | Extracted entities from competitor content |
| `entities[].name` | string | Entity name as it appears in competitor content |
| `entities[].type` | string | Entity classification: `brand`, `topic`, `concept`, `feature`, or `term` |
| `entities[].importance` | string | Importance level: `required` (5+ competitors), `recommended` (2–4), or `optional` (1) |
| `entities[].sourceCount` | number | Number of competitor pages where this entity was found |
| `rankabilityScore` | number | Overall content score (0–100), based on entity coverage (percentage of important competitor entities found in your content) and keyword placement (primary keyword appearing in title, H1, first paragraph, subheadings, meta description) |
| `categoryScores` | object | Internal scoring breakdown by category (returned by the API but not surfaced in the product UI) |
| `scoreDetails` | object | Detailed scoring data including entity coverage percentage, keyword placement checks, and additional analysis metadata |
| `sourceWordCount` | number | Word count of the analyzed page (0 if page could not be scraped) |
| `competitorCount` | number | Number of competitor pages successfully scraped |
| `competitors` | array | Summary of scraped competitor pages |
| `duration` | number | Total processing time in milliseconds |

### How the Rankability score works

The Rankability score (0–100) is derived from two factors:

- **Entity coverage (85% weight)** — The percentage of important entities extracted from competitor pages that your content also covers. Entities are brands, concepts, features, and terms that top-ranking pages mention. Higher coverage means your content addresses the same topics competitors do.
- **Keyword placement (15% weight)** — Whether your primary keyword appears in key on-page locations: the title/H1, the first paragraph, subheadings, and the meta description. Each placement carries a weighted score.

The API response also includes `categoryScores` and `scoreDetails` objects with a more granular internal breakdown, but the product experience centers on entity coverage and keyword placement as the two actionable scoring dimensions.

### Error responses

| HTTP | Error | Description |
|---|---|---|
| 400 | `url is required` | Missing or empty `url` field |
| 400 | `keyword is required` | Missing or empty `keyword` field |
| 400 | `url must be a valid URL` | URL cannot be parsed |
| 400 | `url must use http or https protocol` | Non-HTTP protocol |
| 400 | `url must point to a public host` | SSRF protection — private/internal host detected |
| 401 | `Unauthorized` | Missing or invalid `X-Admin-Key` header |
| 402 | `Insufficient credits` | Not enough credits for this operation |
| 500 | `Entity extraction failed` | No entities could be extracted for this topic |

### Example: Score a page

**Using Bearer token (recommended):**

```bash
curl -X POST https://your-domain.com/api/agent/v1/optimize \
  -H "Authorization: Bearer rk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seo-guide-score-v1" \
  -d '{
    "url": "https://example.com/blog/seo-guide",
    "keyword": "seo guide",
    "language": "en-US"
  }'
```

**Using admin key (legacy):**

```bash
curl -X POST https://your-domain.com/api/v1/optimize \
  -H "X-Admin-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/seo-guide",
    "keyword": "seo guide",
    "language": "en-US"
  }'
```

### Notes

- The Agent API and MCP contracts are asynchronous and durable. The internal admin-key route remains synchronous for the detached runner.
- If the source URL cannot be scraped (bot protection, timeout), the response still includes entities and competitor data but `rankabilityScore` will be `0` and `sourceWordCount` will be `0`.
- Competitor scraping has a 45-second budget — if not all competitors can be scraped within that window, the available results are used.
- Entity extraction targets up to 90 entities from competitor content, verified against SERP data. Only entities found in at least one competitor page are included.
