Skip to main content
POST /api/v1/rank scores and ranks a batch of creatives against one audience. It handles image-only ranking, full ad packages with copy context, platform framing, saved or inline audiences, and pairwise refinement for near ties.
This page covers behavior and interpretation. Field types, schemas, and response shapes live in the Rank API reference, generated from the OpenAPI 3.1 contract.

​
Choosing a goal

goal determines what dimension the assets are scored on. It defaults to purchase-intent, which is the most developed head.
Scores from different goals are not comparable to each other, and scores are only comparable within one batch. Do not build a cross-batch leaderboard out of raw scores.

​
Framing the asset

asset_type changes the system prompt so the simulated persona evaluates the asset in the right mental context. It defaults to Social Media Post. You can set asset_type at the top level and override it per asset. Optionally add delivery context with platform (meta, instagram, facebook, tiktok, linkedin, google), or campaign_type when platform is omitted.

​
Copy context

Attaching copy_context to an asset switches it from image-only scoring to full ad package scoring, and triggers an image-only ablation alongside it. The response gains image_only_score and copy_lift. Preferred keys are pageName, adBody, adHeadline, adCaption, and adDescription. Common aliases are normalized automatically:
An asset with copy_context uses two scoring evaluations when the ablation succeeds — one for full-ad-package, one for image-only. Check score_layer on each ranked asset to see which layer produced the final score.

​
Batch uploads and refinement

Send up to 20 assets per request. Kettio evaluates up to 4 concurrently inside the request and returns a single sorted ranked array. By default (refine_close_pairs: true) Kettio checks successful assets for close pairs. When two scores fall within the refinement threshold, a pairwise panel can run and adjust the final order if it disagrees with the initial SSR ranking. Set refine_close_pairs: false when you want raw SSR-only ordering — for example, when you are running a controlled experiment and need the SSR scores frozen.
Refinement is automatic and threshold-driven. When you already know which specific matchups matter, use the Pairwise API instead — it runs a full five-voter panel on exactly the pairs you name.

​
Handling partial failures

A batch does not fail as a unit. Assets that could not be fetched or scored appear in errors, and the rest still rank. Always read summary.assets_failed before acting on ranked — a “winner” chosen from a batch where half the assets failed is not a winner.

Audiences

Inline vs saved audiences, and the demographics that shape the persona.

Limits and billing

Rate limits and credit accounting, both measured in scoring evaluations.