t1k:marketing:monetization:applovin-max
| Field | Value |
|---|---|
| Module | monetization |
| Version | 1.49.21 |
| Effort | high |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:monetization:applovin-maxAppLovin MAX
Section titled “AppLovin MAX”MAX mediation setup, optimization, revenue reporting integration, and ad-unit network configuration management.
When to Use
Section titled “When to Use”- 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)
Reporting API — endpoint & auth
Section titled “Reporting API — endpoint & auth”- Endpoint:
GET https://r.applovin.com/maxReport - Auth:
api_keyquery param (account-level MAX report key — keep server-side; never ship in a client). - Format:
?format=json(orcsv). Response rows are flat records, one per dimension tuple.
estimated_revenue semantics (critical)
Section titled “estimated_revenue semantics (critical)”estimated_revenueis the TOTAL mediated revenue across ALL networks in the waterfall/bidding auction — NOT AppLovin-network-only. When you group bynetwork, the per-networkestimated_revenuevalues 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, WITHOUTnetwork. Gives network-agnostic request counts. - Call B (placement / network): request columns incl.
network,attempts,responses,estimated_revenue, WITHOUTrequests. 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.tsemits per-network rows from Call B and nullsrequestson them. A regression that LEFT-joined Call A as the spine silently droppednetwork(all rows became'unknown') across a multi-month backfill — seereferences/api-limits-and-auth.md.
Valid groupBy / report dimensions
Section titled “Valid groupBy / report dimensions”day, application, platform, network, ad_format, country, device_type, max_ad_unit_id, max_placement, zone_id.
Limits / quirks
Section titled “Limits / quirks”- 45 days is BOTH the max range AND the total lookback — no chunking strategy reaches older data; a too-early
startreturns 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 — seereferences/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, sojq '.results'dies withparse error: Invalid numeric literal at line 1, column 6and a loop that pipes straight intojqreports a jq bug instead of the real cause. Always check%{http_code}(orhead -c 200the body) before parsing. - Revenue is estimated (finalized later) — recent days can shift; reconcile after the data matures.
- Dates are returned as
YYYY-MM-DDstrings.
Rate limits — verified budget (do not exceed)
Section titled “Rate limits — verified budget (do not exceed)”| API | Base URL | Published limit | Auth |
|---|---|---|---|
| Ad Unit Management | https://o.applovin.com/mediation/v1 | 2,000 requests/hour (≈ 33/min) — documented | Api-Key: header (Management Key) |
| Revenue Reporting | https://r.applovin.com/maxReport | No published limit. Treat as unpublished, not absent — self-throttle | api_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_idreturns 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.
Auth failures — which key, which error
Section titled “Auth failures — which key, which error”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:
| Call | Wrong key used | Response |
|---|---|---|
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 header | 400 → {"errorMessage":{"id":"invalid_parameter",…"description":"Missing header 'Api-Key'"}} |
r.applovin.com/maxReport | Management Key | 403 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_unitsreturns a BARE top-level JSON array, not an object. Noad_unitswrapper key, sojq '.ad_units[]'yields nothing and a loop guarded on.ad_units|lengthexits with zero rows and no error. Usejq '.[]'/ guard onjq 'length'. Differs from/ad_unit/{id}, which does return an object. Paginatelimit=500&offset=N, stop when a page returns< limit.⚠️ GOTCHA —
/ad_unitssilently OMITS disabled units from the listing. Verified 2026-09-22 oncom.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, andselect(.disabled==true)over that listing counted 0, not 14 — the units still exist, andGET /ad_unit/{id}returns each withdisabled: true. Two consequences: (1) a post-write verification that re-lists/ad_unitsand 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_unitsis 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.fieldsis a whitelist, not additive — only the named fields come back; anything else (includingbid_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, …); plusFACEBOOK_NETWORK,APPLOVIN_NETWORK,APPLOVIN_EXCHANGEare bidding. - Waterfall networks require
cpmperad_network_ad_unit(e.g.GOOGLE_AD_MANAGER_NETWORK). - Programmatic classifier: a network is waterfall iff any of its
ad_network_ad_unitscarries acpm; 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:
GET /ad_units→ resolve source and dest IDs by(name, platform, ad_format).GET /ad_unit/{src}?fields=ad_network_settings.- Build body = dest identity (
id,name,platform,package_name,ad_format) +ad_network_settingsfrom source. For bidding-only, drop any network whose units carry acpm; for a full mirror, copy verbatim. POST /ad_unit/{dest}→ expect200; 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 == lengthpasses 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 PASSGuard the comparison itself: a word-splitting bug that feeds
difftwo empty streams reports PASS vacuously. Print line counts alongside the verdict so an empty-vs-empty pass is visible. -
A destination with
disabled: falsestarts 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).
Creating a NEW ad unit (POST /ad_unit)
Section titled “Creating a NEW ad unit (POST /ad_unit)”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:
bun scripts/max-ad-unit.js slots --package com.my.app # what is actually creatablebun scripts/max-ad-unit.js create --package com.my.app \ --platform android --format APPOPEN # DRY RUN by defaultbun scripts/max-ad-unit.js create ... --confirm [--disable-after]# Brand-new package (zero MAX units): opt in explicitly; name is not derivable from siblingsbun scripts/max-ad-unit.js slots --package com.new.app --platform android # all 5 formats freebun scripts/max-ad-unit.js create --package com.new.app --platform android \ --format BANNER --new-package --name NewApp_Banner_ANDIt 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_floorsis NOT a ladder — one floor per country group,INCLUDEonly, a no-fill threshold.bid_floorsis NOT returned unless asked for. A floors-verification re-GET MUST carrybid_floorsinfields(?fields=ad_network_settings,bid_floors), or it verifies nothing.- A non-empty
bid_floorsarray enables the feature (no boolean flag); body still needs the identity fields. country_group_namerejects+and%— alphanumeric/space labels only.- AppLovin dedupes floors on the sent
cpmstring 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
ecpmbycountryfrom the Reporting API (needs the separate Report Key; the Management Key returns403), then POST floors at a markup over each country’s average eCPM.
Hard rules
Section titled “Hard rules”- 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.
References
Section titled “References”- Ad Unit Management API: https://support.applovin.com/en/max/advanced-features/ad-unit-management-api — “This API is rate-limited to 2000 requests per hour.” (
developers.applovin.comandsupport.axon.aimirror it.) - Revenue Reporting API: https://support.applovin.com/en/max/reporting-apis/revenue-reporting-api — “This API has a request window of 45 days.”
- Verified request/response transcripts, dated retrievals, and the corrections behind the gotchas above:
references/api-limits-and-auth.md,references/create-ad-unit.md,references/price-ladder-and-bid-floors.md. - AppLovin MAX Ad Revenue Measurement (impression-level / MAX_REVENUE): https://developers.applovin.com/en/max/android/ad-revenue-measurement/