Skip to content

t1k:marketing:monetization:applovin-max

FieldValue
Modulemonetization
Version1.49.21
Efforthigh
Tools—
/t1k:marketing:monetization:applovin-max

MAX mediation setup, optimization, revenue reporting integration, and ad-unit network configuration management.

  • Integrating MAX SDK and network adapters
  • Setting up in-app bidding
  • Running MAX A/B tests / using the creative debugger
  • Pulling ad-revenue data via the MAX Ad Revenue Reporting API (server-side dashboards, eCPM/ARPDAU analytics, per-network breakdown)
  • Reading/creating/updating ad-unit network config via the Ad Unit Management API (programmatic waterfall + bidding setup, copying networks between ad units)
  • Endpoint: GET https://r.applovin.com/maxReport
  • Auth: api_key query param (account-level MAX report key — keep server-side; never ship in a client).
  • Format: ?format=json (or csv). Response rows are flat records, one per dimension tuple.
  • estimated_revenue is the TOTAL mediated revenue across ALL networks in the waterfall/bidding auction — NOT AppLovin-network-only. When you group by network, the per-network estimated_revenue values sum to the whole-mediation total for that (day, app) — no double-counting.
  • This is why a dashboard’s headline revenue (no network filter) equals SUM(estimated_revenue) over the per-network rows.

The network ⊥ requests conflict (two-call design)

Section titled “The network ⊥ requests conflict (two-call design)”

The MAX Revenue Reporting API column notes (checked 2026-11-16) say: requests cannot show together with network, network_placement or max_placement; attempts, responses and fill_rate only show when network and/or network_placement is included, and cannot show with max_placement. Consequence:

  • Call A (default / requests): request columns incl. requests, impressions, estimated_revenue, WITHOUT network. Gives network-agnostic request counts.
  • Call B (placement / network): request columns incl. network, attempts, responses, estimated_revenue, WITHOUT requests. Gives the per-network revenue decomposition.

The constraint is bidirectional. requests forbids network; attempts, responses and fill_rate need network and/or network_placement to show. So bundle-level fill/response rate always lives on the Call B side; there is no network-agnostic single call that returns fill_rate.

⚠️ Do not add day to a network × country pull. That grain runs ~155k rows/day, so more than a couple of days blows past a practical response size. Pull GEO breakdowns as range totals (omit day) unless a daily series is genuinely required, and pace at ≥ 500 ms as usual.

Merge rule when storing: keep Call B rows as the per-network grain (they carry the real network like ADMOB_BIDDING, APPLOVIN_NETWORK); attach requests from Call A at the network-agnostic grain only — do NOT multiply requests across networks (it inflates request totals). Preserve the invariant SUM(per-network estimated_revenue) == default-report estimated_revenue per (day, app).

Implementation reference (this platform): apps/applovin-api/src/modules/historical/merge-applovin-responses.ts emits per-network rows from Call B and nulls requests on them. A regression that LEFT-joined Call A as the spine silently dropped network (all rows became 'unknown') across a multi-month backfill — see references/api-limits-and-auth.md.

day, application, platform, network, ad_format, country, device_type, max_ad_unit_id, max_placement, zone_id.

  • 45 days is BOTH the max range AND the total lookback — no chunking strategy reaches older data; a too-early start returns HTTP 400. Anything older must come from your own warehouse or a dashboard CSV export, not this API. (An earlier claim of a 90-day lookback here was wrong — see references/api-limits-and-auth.md.)
  • ⚠️ GOTCHA — a range violation returns PLAIN TEXT, not JSON. The body is literally Start date is beyond our 45 day look back period. with no JSON envelope, so jq '.results' dies with parse error: Invalid numeric literal at line 1, column 6 and a loop that pipes straight into jq reports a jq bug instead of the real cause. Always check %{http_code} (or head -c 200 the body) before parsing.
  • Revenue is estimated (finalized later) — recent days can shift; reconcile after the data matures.
  • Dates are returned as YYYY-MM-DD strings.

Rate limits — verified budget (do not exceed)

Section titled “Rate limits — verified budget (do not exceed)”
APIBase URLPublished limitAuth
Ad Unit Managementhttps://o.applovin.com/mediation/v12,000 requests/hour (≈ 33/min) — documentedApi-Key: header (Management Key)
Revenue Reportinghttps://r.applovin.com/maxReportNo published limit. Treat as unpublished, not absent — self-throttleapi_key= query param (Report Key)

⚠️ GOTCHA — neither API returns rate-limit headers. No RateLimit-*, no Retry-After, on either host. You cannot detect that you are approaching the cap — the first signal is the failure itself, so the budget must be counted client-side; a “retry until it stops 429ing” loop is not a substitute.

Self-throttle policy (use these numbers):

  • Management API — hard budget 2,000/h. Plan for ≤ 1,600/h (80%) to leave headroom for retries and for any other process sharing the account key. Sustained pacing: ≥ 2.25 s between calls (1,600/h). A bulk waterfall edit across 250 ad units at 1 GET + 1 POST + 1 verify-GET each = 750 calls — that is 37% of the hourly budget in one run, so two such runs back-to-back will breach it. Count before you loop.
  • Reporting API — no published cap, so pace at ≥ 500 ms between calls and prefer one wide request over many narrow ones: a single call grouped by application,platform,package_name,ad_format,max_ad_unit_id returns the whole account in one request. Do not loop per-app — that turns 1 call into dozens for identical data.
  • On 429: stop the batch, do not hammer. Back off with full jitter (base 2 s, doubling, cap 60 s) and resume from the last confirmed item — never restart the whole batch, which re-spends budget you already paid. AppLovin’s sibling Campaign Management API blocks for ten minutes after a breach; assume similar cooling here rather than an instant recovery.
  • The cap is per ACCOUNT key, not per process. A scheduled crawler plus an interactive session share one budget. Before a bulk write, check what else is running against the same key.

The two keys are not interchangeable, and each rejects the other with a different error. Read the error to tell a wrong-key mistake from a real permission problem:

CallWrong key usedResponse
o.applovin.com/mediation/v1/*Report Key (or a bad Management Key)403 → {"errorMessage":{"id":"access_denied","parameters":[]}}
o.applovin.com/mediation/v1/*key sent as ?api_key= instead of the header400 → {"errorMessage":{"id":"invalid_parameter",…"description":"Missing header 'Api-Key'"}}
r.applovin.com/maxReportManagement Key403 Authentication Failed

access_denied on the Management API with a correct-looking key means the key is wrong or lacks Management access — not that the endpoint is down. Re-copy it from Account → General → Keys; do not brute-force character variants (repeated auth failures are exactly what a rate limiter punishes).

Ad Unit Management API (write — ad-unit & network config)

Section titled “Ad Unit Management API (write — ad-unit & network config)”

A separate API from Reporting — used to list, read, create, and update ad-unit network configurations (waterfall + bidding), including copying networks from one ad unit to another.

  • Base URL: https://o.applovin.com/mediation/v1
  • Auth: Api-Key: <Management Key> HTTP header. The Management Key is distinct from the Reporting Key — dashboard → Account → General → Keys. It grants account-wide write access; treat as a secret and rotate if leaked.
  • Rate limit: 2,000 requests/hour, account-wide. See § “Rate limits — verified budget” above before any bulk loop.

Endpoints:

  • GET /ad_units?fields=ad_network_settings&limit=&offset= — list ad units (basic fields: id, name, platform, ad_format, package_name, has_active_experiment, disabled). Names are not guaranteed unique — resolve a target by (name, platform, ad_format), not name alone. In practice (package_name, ad_format, name) resolves cleanly.

    ⚠️ GOTCHA — /ad_units returns a BARE top-level JSON array, not an object. No ad_units wrapper key, so jq '.ad_units[]' yields nothing and a loop guarded on .ad_units|length exits with zero rows and no error. Use jq '.[]' / guard on jq 'length'. Differs from /ad_unit/{id}, which does return an object. Paginate limit=500&offset=N, stop when a page returns < limit.

    ⚠️ GOTCHA — /ad_units silently OMITS disabled units from the listing. Verified 2026-09-22 on com.mystery.dumpling.unbox.asmr: after disabling 14 of an app’s 20 units, a fresh full paginated listing returned only the 6 still-enabled units, and select(.disabled==true) over that listing counted 0, not 14 — the units still exist, and GET /ad_unit/{id} returns each with disabled: true. Two consequences: (1) a post-write verification that re-lists /ad_units and counts disabled units reads zero on every run, indistinguishable from “the write never landed” — verify a disable by re-GETting each /ad_unit/{id} by id, never by re-listing; (2) any inventory or “this app has N units” claim derived from /ad_units is a claim about enabled units only — say which you mean. The same omission means a disabled unit cannot be rediscovered by name from the listing, so capture its id before disabling it or it must be recovered from the dashboard.

  • GET /ad_unit/{id}?fields=ad_network_settings — network config for the fields named. fields is a whitelist, not additive — only the named fields come back; anything else (including bid_floors) is omitted from the response entirely, not returned empty. See the bid-floors GOTCHA below before treating this as “full config”.

  • POST /ad_unit/{id} — update an ad unit’s network config. Partial / merge — adds/updates only the networks named in the body; networks you omit are left intact (not removed).

  • POST /ad_unit/ — create a new ad unit. GET|POST /ad_unit/{id}/{segment-id} — per-segment waterfalls.

ad_network_settings schema (array of single-key objects, keyed by NETWORK_API_NAME):

{ "ADMOB_BIDDING": {
"disabled": false,
"ad_network_app_id": "ca-app-pub-…~…", // optional, network-specific
"ad_network_app_key": "…", // optional
"targets": {},
"ad_network_ad_units": [
{ "ad_network_ad_unit_id": "…", "disabled": false,
"cpm": "30.00", // WATERFALL only — OMIT for bidding
"countries": {"type": "INCLUDE|EXCLUDE", "values": ["us","ca"]} }
] } }

Bidding vs waterfall:

  • Bidding networks omit cpm (the auction sets price). Names usually end _BIDDING (ADMOB_BIDDING, MINTEGRAL_BIDDING, UNITY_BIDDING, …); plus FACEBOOK_NETWORK, APPLOVIN_NETWORK, APPLOVIN_EXCHANGE are bidding.
  • Waterfall networks require cpm per ad_network_ad_unit (e.g. GOOGLE_AD_MANAGER_NETWORK).
  • Programmatic classifier: a network is waterfall iff any of its ad_network_ad_units carries a cpm; otherwise bidding.

⚠️ GOTCHA — the POST body must carry the destination’s own identity. A POST with only {"ad_network_settings": […]} is rejected:

HTTP 400 {"errorMessage":{"id":"invalid_parameter",
"parameters":{"message":"Invalid parameters passed for: id",
"description":"Ad unit id is not consistent with the request."}}}

The body MUST include the top-level id (matching the URL) plus name, platform, package_name, ad_format, then ad_network_settings. With those, it returns 200.

Recipe — copy networks between two ad units:

  1. GET /ad_units → resolve source and dest IDs by (name, platform, ad_format).
  2. GET /ad_unit/{src}?fields=ad_network_settings.
  3. Build body = dest identity (id,name,platform,package_name,ad_format) + ad_network_settings from source. For bidding-only, drop any network whose units carry a cpm; for a full mirror, copy verbatim.
  4. POST /ad_unit/{dest} → expect 200; re-GET the dest and verify against the source.
  • Merge semantics mean a copy is additive — it won’t wipe networks already on the dest.

  • Copied lines reference the same network-side placement IDs as the source. To get independent placements, mint them on each network’s own dashboard first, then swap the IDs. Consequence: source and dest serve identical network inventory and commingle in each network’s own reporting — correct for a MAX-side split test, wrong when the new unit must be measured independently. Surface this to the user before the write, not after.

  • Verify on a re-GET, never on the POST echo — the POST response reflects what you sent, so it cannot catch a partially-applied write.

  • Assert on content, not counts. length == length passes even when CPMs or placement IDs were mangled. Diff the sorted (cpm, ad_network_ad_unit_id) tuples of the waterfall network:

    Terminal window
    gam() { jq -r '.ad_network_settings[]|to_entries[]|select(.key=="GOOGLE_AD_MANAGER_NETWORK")
    |.value.ad_network_ad_units[]|"\(.cpm)\t\(.ad_network_ad_unit_id)"' "$1" | sort; }
    diff <(gam src.json) <(gam verify.json) && echo PASS

    Guard the comparison itself: a word-splitting bug that feeds diff two empty streams reports PASS vacuously. Print line counts alongside the verdict so an empty-vs-empty pass is visible.

  • A destination with disabled: false starts serving the moment the config lands — no separate activation step. Confirm the unit is meant to go live before POSTing.

Money-risk: these are live writes that change served ads / revenue. Confirm the account, show a before→after diff before POSTing, and never bulk-loop writes without per-item verify (see the ad-network-mcp-write-safety rule).

POST https://o.applovin.com/mediation/v1/ad_unit — one unit per request. Returns 200 (not 201) with the full unit object including its new id.

{ "name": "MyApp_AOA_AND", "platform": "android",
"package_name": "com.my.app", "ad_format": "APPOPEN" }

All four fields are required. There is no app_id field — the app is addressed by package_name + platform. Native units additionally require template_size.

ad_format values: APPOPEN, BANNER, INTER, MREC, REWARD. (The published docs list only INTER/BANNER/REWARD; APPOPEN and MREC are equally valid and in live use.)

⚠️ HARD RESTRICTION — one ad unit per (package_name, platform, ad_format). A second create for a combination that already has an active unit is refused:

HTTP 400 {"errorMessage":{"id":"invalid_parameter","parameters":{
"message":"Invalid parameters passed for: ad_format, platform, package_name",
"description":"Cannot use the API to create multiple ad units for the same ad format/app/platform, Please use the UI."}}}

So the API can only fill empty slots. Before offering to create anything, GET /ad_units, build the set of occupied (package, platform, format) tuples, and present the free slots — otherwise you are proposing writes that cannot succeed.

⚠️ Do not read “free slot” as “missing ad unit”. Accounts routinely run several units of the same format on one app for waterfall depth — a base unit plus _1.. _N siblings (observed in production: 8 INTER and 8 REWARD on a single package, all enabled). Those siblings are UI-only; the API refuses to make them. So the creatable-slot count is a statement about the API’s reach, not about how many units the app ought to have. Say which you mean when reporting it.

⚠️ GOTCHA — a newly created unit is NOT inert. The response ships ad_network_settings pre-populated with APPLOVIN_NETWORK and APPLOVIN_EXCHANGE, both disabled: false, and the unit itself is disabled: false. It can begin serving AppLovin demand as soon as the app requests that format — you do not get a staging state. If the unit is not meant to go live, plan the follow-up POST /ad_unit/{id} that disables it before creating it.

Not reversible: ad units can be disabled but not deleted. Confirm the target app, platform, and format with the user before the write, and match the account’s existing naming convention (read sibling unit names from GET /ad_units rather than inventing one).

Use the bundled script rather than hand-rolling curl — it enforces every guard above:

Terminal window
bun scripts/max-ad-unit.js slots --package com.my.app # what is actually creatable
bun scripts/max-ad-unit.js create --package com.my.app \
--platform android --format APPOPEN # DRY RUN by default
bun scripts/max-ad-unit.js create ... --confirm [--disable-after]
# Brand-new package (zero MAX units): opt in explicitly; name is not derivable from siblings
bun scripts/max-ad-unit.js slots --package com.new.app --platform android # all 5 formats free
bun scripts/max-ad-unit.js create --package com.new.app --platform android \
--format BANNER --new-package --name NewApp_Banner_AND

It reads APPLOVIN_MANAGEMENT_KEY from .env, paces to 80% of the hourly cap, refuses an occupied slot locally before spending a write, derives the unit name from that app’s own sibling naming, verifies on a re-GET, and can disable the unit immediately after creation.

Full verified request/response transcripts: references/create-ad-unit.md.

Price ladders and bid floors (summary — detail in references/price-ladder-and-bid-floors.md)

Section titled “Price ladders and bid floors (summary — detail in references/price-ladder-and-bid-floors.md)”
  • The API can build only ONE ad unit per (package, platform, ad_format). Rungs 2..N of a same-format ladder are dashboard-only; never quote a ladder rollout as “the API can do it”. Automate floor-setting, not creation.
  • NEVER create sibling rungs for a format whose default unit has no real waterfall (cpm_lines == 0 → stop, configure the default first). Order: configure default → clone → set floors.
  • Read-modify-write, and a partial write DESTROYS lines. Within one network, omission is deletion: always GET, mutate in memory, POST the whole array back, re-GET and assert the line count.
  • Price points live in ad_network_settings[].ad_network_ad_units[].cpm (API-writable). Segment waterfalls partition USERS, not requests, and segment CREATION is unproven — probe a throwaway unit first. There is no escape hatch around the one-unit cap.
  • bid_floors is NOT a ladder — one floor per country group, INCLUDE only, a no-fill threshold.
  • bid_floors is NOT returned unless asked for. A floors-verification re-GET MUST carry bid_floors in fields (?fields=ad_network_settings,bid_floors), or it verifies nothing.
  • A non-empty bid_floors array enables the feature (no boolean flag); body still needs the identity fields.
  • country_group_name rejects + and % — alphanumeric/space labels only.
  • AppLovin dedupes floors on the sent cpm string ALONE: NEVER pre-round to 2 decimals — send ~4-decimal values ((ecpm*mult).toFixed(4)), then re-GET and assert stored count == sent count.
  • Data-driven floors: pull last-7d ecpm by country from the Reporting API (needs the separate Report Key; the Management Key returns 403), then POST floors at a markup over each country’s average eCPM.
  • MAX in-app bidding (IAB) requires every adapter to support IAB — a single waterfall network in IAB-mediation can collapse fill in low-eCPM geos. Audit adapter compatibility per network release.
  • MAX A/B experiments are placement-scoped, not segment-scoped — segmentation must be done via segments + experiments together, not experiments alone.
  • Creative debugger only works on test devices — production fill cannot be inspected; pre-flight all creatives before go-live.
  • ARPDAU shifts on weekends — never compare a Tuesday cohort to a Saturday cohort when judging a MAX experiment.