Limits and billing

Ranking API access

Self-serve ranking API access requires Professional or another API-enabled plan. Professional includes 500 ad rankings per calendar month and up to 20 ads per request. Free and Starter accounts can rank ads in the web app; they do not include self-serve API access.

Monthly ad allowance

Each successfully ranked ad uses one ad ranking, including ads scored with copy context and an image-only ablation. Failed assets do not consume the allowance. Upload, dashboard, and self-serve ranking API usage share the same account allowance. The allowance resets on the first day of each calendar month at 00:00 UTC. Unused rankings do not roll over. Ranking does not spend the separate generation credit balance.

Organization-scoped partner integrations follow their separately agreed access and billing contract. The monthly allowance described here applies to self-serve ranking.

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

Rate limits measure evaluation work separately from the monthly ad allowance:

Asset shape	Scoring evaluations	Ad rankings on success
Image only	1	1
With `copy_context` and a successful ablation	2	1
With `copy_context` and a failed ablation	1 successful evaluation	1
Failed asset	Failed work can still count toward the rate limit	0

Each evaluation contains three paired-model repetitions (six generator samples). Repetitions do not multiply the monthly ad charge.

Reading usage from the response

{
  "summary": {
    "assets_ranked": 1,
    "assets_failed": 0,
    "scoring_evaluations": 2,
    "repetitions_per_evaluation": 3,
    "generator_samples_per_evaluation": 6,
    "ad_rankings_used": 1,
    "ad_rankings_remaining": 499,
    "credits_used": 0,
    "credits_remaining": null
  }
}

Use ad_rankings_used and ad_rankings_remaining for the monthly allowance. The retained credits_used and credits_remaining fields are 0 and null for self-serve ranking. scoring_evaluations describes successful evaluation work, not the monthly ad charge.

Pairwise billing

The standalone Pairwise API uses the separate credit balance and reports pairwise_evaluations.

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

Automatic close-pair refinement inside a Rank API request is reported under summary.close_pair_refinement and does not add another ad-ranking charge.

Handling limits

402: not enough ad rankings remain for the batch. Wait for the monthly reset or change plan.
403: the account does not have ranking API access.
429: evaluation rate limit reached. Honor the Retry-After header.

See the agent loop guide for a backoff example.

Estimating rate-limit work

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

A 20-ad batch with copy context can require 40 evaluations while consuming 20 ad rankings.

Get started

Guides

Concepts

MCP server

Changelog

Limits and billing

Ranking API access

Monthly ad allowance

Rank API limits

Reading usage from the response

Pairwise billing

Handling limits

Estimating rate-limit work

​Ranking API access

​Monthly ad allowance

​Rank API limits

​Reading usage from the response

​Pairwise billing

​Handling limits

​Estimating rate-limit work

Ranking API access

Monthly ad allowance

Rank API limits

Reading usage from the response

Pairwise billing

Handling limits

Estimating rate-limit work