Skip to main content
A placement is a named slot in your UI where an ad can appear. Placements are a first-class concept in Gravity because they’re where three things come together:
  1. Fill — is there a campaign that wants to serve here?
  2. Match quality — how relevant is what we serve to the conversation?
  3. UX — how does the ad feel in your product?
Those three tradeoffs are almost always the biggest lever on revenue for a given AI platform. Placements are how you operate on them.

​
Why placements matter

  • Per-slot economics. The dashboard reports impressions, CTR, and revenue per placement_id. You’ll see a below_response slot earn very differently from a right_response sidebar. That’s actionable — you learn which spots in your UI carry their weight.
  • Scoped experimentation. Gravity can run experiments targeted to a specific placement. Test a new format in your right rail without touching your primary in-flow slot.
  • Auto-optimization. The engine learns which ad formats work best per placement over time, and leans into the winners. This only works if you’ve declared the slots in the first place.
  • Fill-rate tuning. Different placements tolerate different fill rates. A page-level bottom_page slot might want 95% fill (low relevance bar); an inline_response slot might want 40% fill (only serve when the match is strong). Separate placements let you set different policies.

​
Standard placement types

​
Creating placements in the dashboard

The dashboard under AI platforms → Placements lets you register the slots in your UI by placement_id. This is also where per-slot reporting lives and where you configure any placement-scoped experiments we run on your traffic. Placements are created in the dashboard. There is no public API for creating them — the platform API only reads placements (GET /publisher-dashboard/placements, publisher_get_placements). Sending a new placement_id in an ad request does not create it.
Register a placement before you send it. Once your account has any placements defined, the engine filters each ad request down to your active placement identifiers (slug or UUID). An unregistered placement_id sent alongside registered ones is dropped from the auction — that slot gets no ad, with no error on the response. The only exception is an account with no placements defined at all, or a request where every placement_id is unrecognized; those serve unfiltered for backward compatibility.A newly created placement can take up to 15 minutes to become servable while the placement cache refreshes.

​
placement_id — your slot name

Every placement needs a placement_id that identifies the specific slot:
Pick any stable string. 'chat-main', 'mobile-footer', 'search-result-3' — whatever maps to the spot in your UI. Register it in the dashboard, then use it consistently; your dashboard reports revenue and CTR per placement_id.

​
Up to 10 per request

You can request ads for up to 10 placements in one call. They share the same auction, so there’s no rate-limit penalty to asking for everything on a page.

​
No-fill is normal

If the engine has no matching campaign for a slot, that slot returns null (or the array index is absent). Always render conditionally:
The fill rate depends on:
  • How relevant your content is to active campaigns
  • The relevancy threshold you set — see request-ads → relevancy tradeoff
  • Advertiser budget availability at the moment
You can tune fill rate up by lowering the relevancy threshold on the Gravity constructor — but be aware tighter matches tend to convert better.

​
Next

Experiments

How Gravity runs placement-scoped experiments on your traffic.