Auction API Explained: How Real-Time Ad Auctions Work

An auction API is a service that takes a monetizable impression, a set of eligible advertisers or sponsored items, and their bids, then returns the winner, placement, and price in real time.

The API call is the small part.

Behind it sits eligibility filtering, relevance or quality scoring, budget enforcement, pacing, auction logic, pricing, placement rules, and an event ledger that eventually has to explain exactly why an advertiser was charged.

For a marketplace, search product, feed, directory, or recommendation surface, that is the real engineering problem.

This guide takes the request apart.

At its simplest, an auction API answers:

Given this user, this context, these available sponsored positions, and these advertisers willing to pay for them, what should we show and what should each winner pay?

A request might look conceptually like this:

{
  "surface": "marketplace_search",
  "query": "running shoes",
  "slots": 2,
  "candidates": [
    {
      "item_id": "shoe_101",
      "bid": 1.80
    },
    {
      "item_id": "shoe_204",
      "bid": 2.20
    },
    {
      "item_id": "shoe_318",
      "bid": 1.60
    }
  ]
}

And the response might return:

{
  "winners": [
    {
      "item_id": "shoe_204",
      "slot": 1,
      "price": 1.74
    },
    {
      "item_id": "shoe_101",
      "slot": 2,
      "price": 1.51
    }
  ],
  "auction_id": "auc_01J..."
}

But production auctions almost never sort candidates by raw bid and take the highest bidder.

The actual request path is closer to:

request → eligibility → quality scoring → auction → pricing → placement → logging

Each stage exists because maximizing the bid is not the same as maximizing the value of the surface.

1. An impression creates an auction opportunity

The process starts when your application has inventory it can monetize.

That could be:

• position 1 in marketplace search

• position 4 in a product feed

• the first sponsored recommendation

• a promoted restaurant in local discovery

• a sponsored seller in a category page

Your application knows the context: user, query, category, candidate set, device, placement and session.

That context becomes the auction request.

“Real time” matters because the winner usually has to be selected while the user is waiting for the underlying page or feed.

The auction is therefore part of the serving path, not a background analytics job.

2. Filter to eligible advertisers

Not every campaign should enter every auction.

Before comparing bids, the system normally removes candidates that cannot legally or economically win.

Eligibility can depend on:

• targeting

• geography

• category

• remaining budget

• campaign status

• inventory availability

• frequency caps

• advertiser permissions

• creative approval

• minimum relevance

This step matters more than it appears.

An auction cannot repair bad candidate selection.

If an irrelevant advertiser reaches the auction and is allowed to win purely because it bids aggressively, the pricing mechanism is functioning correctly while the product experience is failing.

A useful rule is:

Eligibility decides who is allowed to compete. The auction decides which eligible candidate wins.

Consider two advertisers bidding for the same sponsored position.

Advertiser A bids $3.00 per click and has an estimated 0.3% click-through rate.

Advertiser B bids $1.50 per click but has a 1.2% expected click-through rate.

Ranking only by bid gives the slot to Advertiser A.

Expected revenue tells a different story.

For CPC campaigns, a simplified effective CPM is:

eCPM = CPC bid × p(click) × 1,000

So:

Advertiser A

$3.00 × 0.003 × 1,000 = $9 eCPM

Advertiser B

$1.50 × 0.012 × 1,000 = $18 eCPM

Advertiser B is worth twice as much per thousand impressions despite offering half the CPC bid.

That is why auction systems often rank candidates using some form of:

rank score = bid × quality

The quality component might represent:

• predicted click probability

• predicted conversion probability

• query relevance

• listing quality

• user-item affinity

• marketplace-specific business constraints

This begins to overlap with the work normally handled by a ranking API.

Money determines willingness to pay. Quality determines whether winning that money is worth the impression.

Selecting a winner and deciding what the winner pays are separate problems.

That distinction produces different auction mechanisms.

First-price auction

Suppose three advertisers bid:

• A: $5

• B: $4

• C: $2

In a simple first-price auction, A wins and pays $5.

The mechanism is simple and transparent operationally, but advertisers have an incentive to estimate what competitors might bid and shade their own bids below their true maximum value.

Large programmatic exchanges increasingly use first-price mechanics. Google, for example, moved Ad Exchange inventory to a unified first-price auction, and its current Open Bidding documentation describes real-time bids competing in a unified auction where the highest net bid wins.

Second-price auction

With the same bids:

• A: $5

• B: $4

• C: $2

A still wins, but instead of paying $5, the clearing price is based on the next-best bid.

Conceptually, A pays approximately $4 rather than its full $5 willingness to pay.

The appeal of a classic single-slot second price auction is incentive alignment: bidders can bid closer to what the impression is genuinely worth to them rather than constantly trying to predict the exact market-clearing price.

Production systems usually add reserve prices and quality adjustments, so the implementation is rarely as simple as “second-highest bid plus one cent.”

A GSP auction, or generalized second-price auction, extends the concept to multiple ordered slots.

Suppose a search page has three sponsored positions.

Candidates are ranked:

1. Advertiser A

2. Advertiser B

3. Advertiser C

4. Advertiser D

A receives slot 1, B receives slot 2 and C receives slot 3.

Instead of automatically charging each advertiser its own bid, the system calculates the price required for that advertiser to maintain its position relative to the competitor below it.

With quality-adjusted ranking, a simplified CPC clearing formula is:

price_i = next competitor's rank score / winner's quality score

That produces an important property.

A high-quality advertiser can sometimes win while paying less than an advertiser with a larger raw bid because its expected value to the surface is higher.

GSP is particularly useful to understand when building sponsored search or marketplace advertising, where multiple paid positions may be auctioned on the same request.

This is where “build an auction” projects usually become larger than expected.

The actual auction function might fit in a relatively small amount of code.

A production monetization system does not.

You also need:

Budget state

A $10,000 daily campaign cannot be allowed to spend $14,000 because hundreds of servers simultaneously believed $20 remained in the account.

Budget systems need fast reads, reliable writes and reconciliation.

Pacing

Without pacing, strong campaigns can spend their daily budget during the first few hours of traffic.

The system therefore has to decide not only whether an advertiser can win, but whether it should be allowed to win now.

Frequency caps

A profitable auction can still create a terrible product if the same user sees the same advertiser repeatedly.

Frequency is another stateful constraint on eligibility.

Reserve prices

You may not want to sell an impression below some minimum economic value.

A floor or reserve price prevents weak demand from clearing inventory too cheaply.

Event tracking

The winning auction creates a financial obligation.

You need to know whether the ad was rendered, viewed, clicked and converted.

Those events need to point back to the original auction or decision.

Auditability

When an advertiser asks:

Why did I pay $1.82 for this click?

“Because the model said so” is not a billing system.

You need enough information to reconstruct the decision: eligible candidates, scores, pricing rule, clearing price, campaign state and resulting placement.

The moment an algorithm moves money, observability stops being optional.

For engineering teams evaluating an auction API, the response should contain more than a winner ID.

Useful fields can include:

• winner

• slot

• clearing price

• pricing model

• auction ID

• campaign ID

• decision ID

• relevant score

• tracking identifiers

• debug or explanation data

The identifiers matter especially.

Your impression, click, conversion, billing and reporting systems need a durable way to refer to the exact decision that produced the placement.

Without that lineage, discrepancies become extremely difficult to debug.

They overlap, but they are not necessarily the same product.

An auction API primarily answers:

Who wins this inventory, and at what price?

An ad server API may additionally own:

• campaign creation

• targeting

• creatives

• advertiser accounts

• budgets

• pacing

• attribution

• reporting

• billing

• forecasting

That difference matters for product teams.

If you already have a marketplace catalog, search system, UI, advertiser relationships and event infrastructure, replacing all of it with a full ad server can be excessive.

You may only need the decisioning and pricing layer.

The most useful architectural question is not always “Which auction API should we integrate?”

It is:

Should auctioning be another independent system that your ranking stack has to reconcile afterward?

For consumer platforms, that creates an awkward boundary.

One system decides the best organic order. Another selects ads. A third piece of application logic then tries to merge the two without destroying relevance.

Gortex is built around a different boundary: ranking and monetization belong to the same decision layer.

The current Gortex decisioning API accepts candidates and context and returns the ranked result together with sponsored slots in the same decision flow, rather than treating monetization as an unrelated system bolted onto the page.

That becomes especially useful for marketplaces, feeds and recommendation products where the paid result is displacing something that would otherwise have been shown organically.

The auction cannot only ask:

Which advertiser is worth the most?

It also has to ask:

Is this advertiser worth showing instead of the organic item that would occupy this position?

That is a ranking problem and a monetization problem at the same time.

For a CTO or engineering lead, start with the request path rather than the feature list.

Ask:

Can it fit inside our serving latency budget?

An auction that adds unacceptable tail latency is not production-ready for your surface.

How are relevance and quality incorporated?

Raw bid ordering is rarely enough for native sponsored inventory.

Which auction mechanisms are supported?

First price, second price and GSP solve different market-design problems.

How are budgets and pacing enforced?

Ask what happens under concurrent traffic, not only in the happy-path demo.

Can every result be replayed or explained?

Money-moving decisions need deterministic enough records to investigate disputes.

How are events reconciled?

Understand how impressions, clicks and conversions connect to auction decisions.

How does the system interact with organic ranking?

For marketplaces and feeds, this may matter more than the auction algorithm itself.

And finally:

Are you buying an API, or accidentally adopting an entire advertising platform?

The right boundary depends on what you already own.

An auction API turns a monetizable impression into a priced decision.

The production path is:

context → eligible advertisers → quality scores → auction → clearing price → placement → event ledger

The auction formula is only one part of the system.

The difficult engineering lives around it: budget consistency, pacing, relevance, latency, event reconciliation and making sure paid inventory does not quietly degrade the product it monetizes.

If advertising itself is your core technology, owning that stack can make sense.

If your real product is a marketplace, feed, search experience or recommendation surface, there is a strong argument for keeping auction and sponsored-placement infrastructure behind an API—and keeping it close enough to organic ranking that revenue does not fight relevance.

That is the decision boundary Gortex is designed around.

Explore Gortex's decisioning and Sponsored Listings API if you want to monetize ranked inventory without building the entire decision layer in-house.

1. What is an auction API?

An auction API is an interface that receives an impression or placement opportunity, evaluates eligible bidders, runs an auction and returns the winning advertiser or sponsored item together with its price and decision metadata.

2. How does a real-time ad auction work?

A request is created when monetizable inventory becomes available. Eligible advertisers are filtered, bids are combined with quality or relevance signals, candidates are ranked, a pricing rule determines what the winners pay, and the result is returned for rendering. The decision is then logged for tracking and billing.

3. What is the difference between first-price and second-price auctions?

In a first-price auction, the winner generally pays its own bid. In a classic second-price auction, the highest bidder wins but pays a price based on the next-highest competing bid, subject to the auction's reserve and pricing rules.

4. What is a GSP auction?

A generalized second-price, or GSP, auction is a multi-slot auction commonly associated with ranked advertising inventory. Multiple winners receive ordered positions, and each winner's price is based on what is required to maintain its position relative to the bidder below it.

5. Is an auction API the same as an ad server?

No. An auction API can focus narrowly on candidate ranking, winner selection and pricing. An ad server may additionally handle campaign management, targeting, creatives, budgets, pacing, attribution, reporting and advertiser tooling.

6. Do sponsored listings always go to the highest bidder?

They should not have to. Modern sponsored-ranking systems can combine bids with predicted performance, relevance and quality. That allows a more useful ad with a lower raw bid to outrank a higher-paying but less relevant candidate.

7. Should I build an auction engine or use an API?

Build when auction mechanics are a core competitive advantage and you have the engineering resources to continuously own pricing, quality models, pacing, budget state, billing and experimentation. An API is more attractive when monetization is important but the auction infrastructure itself is not your product.