Optimize API endpoint

Run a synchronous Rankability Optimize analysis for a public URL and keyword, with explicit retry protection and success-based billing.

Use Optimize to score one existing public page against current search competitors for a target keyword. It is a synchronous, stateless analysis: it does not create a Copywriter project or require polling.

Scope, endpoint, and cost

The key needs optimize:run.

POST https://app.rankability.com/api/agent/v1/optimize

A successful analysis consumes one Core optimization allowance or, for a legacy Full shared-credit account, 400 credits. Rankability checks affordability before analysis and charges after a usable response is produced. Read the active contract from GET /api/agent/v1/usage and estimate the operation with GET /api/agent/v1/usage/estimate?operation=optimize_page instead of inferring price from the account balance.

This standalone, stateless API operation is different from creating a persistent Copywriter existing-content optimization, which uses the separate Copywriter outcome rate documented in Creating content jobs.

Send the request

curl -X POST https://app.rankability.com/api/agent/v1/optimize \
  -H "Authorization: Bearer rk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: optimize-example-seo-guide-v1" \
  -d '{
    "url": "https://example.com/seo-guide",
    "keyword": "seo guide",
    "language": "en-US"
  }'

Field	Required	Behavior
url	Yes	Public HTTP or HTTPS page to score
keyword	Yes	Target query used for competitor research and scoring
language	No	Language code up to 10 characters, such as en-US; defaults to en-US

Private IP ranges, localhost, link-local addresses, .local or .internal hosts, and cloud metadata targets are rejected.

Retry protection is explicit

Always send a stable Idempotency-Key when the same logical request might be retried. The customer Agent API does not promise that sending the same URL and keyword without that header will be free or deduplicated.

Store the response before retrying. A client timeout does not prove the server failed before completing the work.

Read the response

The response returns when analysis completes and can include:

• rankabilityScore — the overall 0–100 score when the page could be scored.

• categoryScores and scoreDetails — category and evidence breakdowns.

• entities — competitor-derived entities and coverage information.

• sourceWordCount — words extracted from the submitted page.

• competitorCount and competitors — successfully analyzed comparison pages.

• duration — total processing time in milliseconds.

• The normalized url, keyword, and language.

Competitor pages that cannot be fetched are omitted from the successful competitor summary. A smaller comparison set reduces the evidence available; it does not mean Rankability verified every result page.

Scores reflect the page and competitor evidence available during that request. Search results, accessible competitors, and page content can change, so compare repeated analyses as dated observations rather than a permanent grade.

Plan for a long synchronous request

Optimize retrieves live search results, fetches the submitted page and eligible competitors, extracts entities, and scores the content. Calls can take tens of seconds. The Agent API allows the internal analysis up to 180 seconds.

Use an HTTP client timeout longer than the expected request, but keep your own upper bound. Do not convert Optimize into aggressive parallel batch traffic without respecting returned request-rate headers and available credits.

Common failures

Status	Code	Action
400	validation_error or optimize_error	Correct a missing, invalid, unsafe, or inaccessible input
401	unauthorized	Replace or correct the key
402	insufficient_credits	Add credits or reduce planned work
403	forbidden	Grant optimize:run to the intended key
429	rate_limit_exceeded	Wait for the returned reset interval
502	optimize_unavailable	Retry later with a bounded attempt count
504	optimize_timeout	Retry later; do not loop immediately

Use Page Auditor API endpoints instead when you need a durable asynchronous audit record with gate results. See API credits, rate limits, and errors for production retry rules.