Limits and billing

The single most important thing to internalize: Kettio bills and rate-limits by scoring evaluation, not by asset. An agent that budgets by asset count will hit 429 earlier than it expects.

Rank API limits

Limit	Value
Maximum assets	20 per request
Concurrency	Up to 4 assets evaluated at a time inside the request
Rate limit	60 scoring evaluations per minute per API key
Close-pair refinement	At most 6 pairs per request

What an evaluation costs

Asset shape	Evaluations
Image only	1
With `copy_context` (ablation succeeded)	2 — full ad package plus image-only ablation
With `copy_context` (ablation failed)	1
Failed asset	0 — failures are not billed

Each evaluation contains three paired-model repetitions (six generator samples), but credits are deducted per successful scoring evaluation — not per repetition and not per model call.

A 20-asset batch where every asset carries copy context can cost up to 40 evaluations. That is two thirds of your per-minute allowance in a single request.

Reading usage from the response

{
  "summary": {
    "assets_ranked": 1,
    "assets_failed": 0,
    "scoring_evaluations": 2,
    "repetitions_per_evaluation": 3,
    "generator_samples_per_evaluation": 6,
    "credits_used": 2,
    "credits_remaining": 48
  }
}

Track scoring_evaluations and credits_remaining rather than counting requests.

Pairwise billing

The Pairwise API is accounted separately and reports pairwise_evaluations on its own.

Result	Billed
Completed five-voter panel	1 credit
`partial`	Not billed
`error`	Not billed

Close-pair refinement inside the Rank API is reported under summary.close_pair_refinement; Rank API credit and rate accounting is based on scoring evaluations.

Handling 429

429 responses carry a Retry-After header. Honour it instead of retrying on a fixed interval — there is a worked backoff implementation in the agent loop guide.

Estimating before you send

function estimateEvaluations(assets) {
  return assets.reduce(
    (total, asset) => total + (asset.copy_context ? 2 : 1),
    0,
  );
}

This is an upper bound — failed assets and failed ablations both come in under it.

Get started

Guides

Concepts

MCP server

Changelog

Limits and billing

Rank API limits

What an evaluation costs

Reading usage from the response

Pairwise billing

Handling 429

Estimating before you send

​Rank API limits

​What an evaluation costs

​Reading usage from the response

​Pairwise billing

​Handling 429

​Estimating before you send

Rank API limits

What an evaluation costs

Reading usage from the response

Pairwise billing

Handling 429

Estimating before you send