Skip to content

t1k:marketing:monetization:mintegral

FieldValue
Modulemonetization
Version1.49.21
Efforthigh
Tools—
/t1k:marketing:monetization:mintegral

Mintegral Open API reporting — advertiser (AppGrowth performance) and publisher (monetization) surfaces.

  • Pulling publisher ad-revenue (IAA) data: est_revenue, eCPM, fill_rate per app/placement/unit
  • Pulling advertiser/UA campaign cost: spend, impressions, conversions, eCPM per campaign/creative
  • Building a Mintegral revenue or UA cost dashboard
  • Handling SKAdNetwork (SKAN 4.0) iOS measurement via report dimensions
  • Generating the nested-MD5 auth tokens for either surface
  • Active management (bids, budgets, pause/resume, eCPM floors, creating offers/apps/placements/units) — via the Mintegral MCP, see “MCP Orchestration” below

Mintegral exposes two completely separate reporting products. Pick by role:

SurfaceHostAuthUse for
Advertiser / AppGrowthss-api.mintegral.comHTTP headers (access-key/token/timestamp)UA campaign-spend performance (impressions, clicks, conversions, spend, eCPM)
Publisher / Monetizationapi.mintegral.comQuery params (skey/sign/time)Ad-revenue / monetization (est_revenue, eCPM, fill_rate, hb_load)

A monetization (IAA) dashboard almost always wants the publisher surface. A UA cost dashboard wants the advertiser surface. Do not mix hosts or auth schemes.

MCP Orchestration & Active Management (writes)

Section titled “MCP Orchestration & Active Management (writes)”

The raw reporting APIs documented here are read-only. For active management — bids, budgets, pause/resume, eCPM floors, creating offers/apps/placements/units — use the Mintegral MCP server (@theonekit/mintegral-mcp-server, from The1Studio/theonekit-ads-mcp) when it is installed. It wraps the same nested-MD5 auth and exposes 17 mintegral_* tools (6 read, 11 guarded write); it is the preferred path for any mutation.

Confirm availability — mintegral_list_offers (etc.) appears in the tool list. If absent, tell the user to install the MCP from theonekit-ads-mcp; do NOT hand-roll write calls against the raw API.

Guarded-write discipline (ALWAYS):

  • Writes are off by default — both MINTEGRAL_ALLOW_WRITES=1 (server env) AND a per-call confirm:true are required to mutate. Otherwise a write tool returns a preview only.
  • Preview first: show the diff, get explicit go-ahead, THEN send confirm:true. Never silently flip the kill-switch.
  • Offer writes refuse account-managed offers (maintain_by != "ADV") — report it, don’t retry.
  • Read the relevant report before recommending a write, so the bid/floor/budget number is evidence-based.

Tools — reads: mintegral_list_offers, mintegral_get_campaign_report, mintegral_list_placements, mintegral_list_apps, mintegral_list_units, mintegral_get_publisher_report; writes (guarded): mintegral_create_offer, mintegral_update_offer, mintegral_set_offer_status, mintegral_update_bid, mintegral_update_budget, mintegral_create_app, mintegral_create_placement, mintegral_create_unit, mintegral_update_unit, mintegral_update_placement, mintegral_update_app.

Playbooks (copy-ready steps in references/mcp-playbooks.md): bid optimization, pause underperformers, budget reallocation, eCPM-floor tuning, campaign/unit launch, revenue & fill analysis.

Both schemes use nested MD5 with a Unix-seconds timestamp — Mintegral labels it “token” but it is NOT true HMAC. Do not reach for crypto HMAC libraries.

Headers: access-key, token, timestamp.

timestamp = <unix seconds>
token = md5( api_key + md5(timestamp) )

PHP reference: $token = md5($api_key . md5($timestamp));

Credentials: api_key + access-key from Account Management > Basic Information.

Query params: skey, sign, time.

time = <unix seconds>
sign = md5( SECRET + md5(time) )

The time value must be within a ±300-second window of the Mintegral server clock.

Credentials: skey + SECRET (private key) from API Tools > Reporting API.

  • Advertiser / AppGrowth performance: https://ss-api.mintegral.com
  • Publisher / monetization: https://api.mintegral.com

Monetization Reporting Endpoint (publisher)

Section titled “Monetization Reporting Endpoint (publisher)”

GET https://api.mintegral.com/reporting/v2/data (v1 path: /reporting/data — prefer v2).

Synchronous JSON — no async two-step. Request Content-Type: application/x-www-form-urlencoded; response application/json.

Key params:

ParamNotes
skey, sign, timeauth (see above)
startYYYYMMDD
endYYYYMMDD, max 7-day span, ~60-day history
timezone-12..12, default 8
group_byCSV: date,country,app_id,platform,placement_id,unit_id,bidding_type,timestamp
pagepagination
limitdefault/max 10000
app_id / placement_id / unit_id / ad_formatCSV filters

Metrics returned: est_revenue, ecpm, request, impression, click, filled, fill_rate, ctr, hb_load, hb_load_filled (header-bidding).

GET https://ss-api.mintegral.com/api/v2/reports/data (v1: /api/v1/reports/data — prefer v2 / advancedPerformanceReport).

Async two-step flow:

  1. type=1 (default) — trigger async generation / poll status. Returns code 200 (ready), 201/202 (still generating), 10000 (param/permission error).
  2. type=2 — download data once status is 200. Returns a byte stream: tab-separated columns, newline-separated rows (TSV, NOT JSON).

Key params:

ParamNotes
start_timeYYYY-mm-dd, required, max 6-month lookback
end_timeYYYY-mm-dd, required, max 7-day span
dimension_optionCSV: Offer,Campaign,CampaignPackage,Creative,AdType,Sub,Package,Location,Endcard,AdOutputType
type1 poll status (default), 2 download
time_granularitydaily (default) / hourly
timezonedefault +8

TSV columns include: Impression, Click, Conversion, CTR, CVR, IVR, eCPM, CPC, Spend, Currency (USD/CNY). Data available ~1.5h after day close; generated files retained 1 month.

Mintegral supports SKAN 4.0, but there is no dedicated SKAN reporting endpoint. SKAN data surfaces through the standard advertiser performance report (/api/v2/reports/data) via dimensions:

  • dimension_option campaign/creative
  • SKAdNetwork conversion value (0-63)
  • fidelity type

Values are aggregated and privacy-thresholded — conversion value may be null below Apple’s privacy threshold, and postbacks are delayed (no real-time SKAN). A true SKAN postback/raw feed is partner/MMP-mediated, not in the public reporting API.

  • Max 7-day span per request on both surfaces. The cap is enforced silently on the advertiser surface — a request wider than ~7 days returns an empty / $0 payload with HTTP success and no error code. NEVER pass a >7-day window in one call.
  • Chunk-and-sum any longer window. Walk the requested range in contiguous ≤7-day slices, issue one request per slice, and SUM the additive metrics (spend / installs / clicks / impressions / est_revenue / est_revenue-derived volumes). Recompute ratios (CPI, eCPM, fill, CTR) from the summed numerators/denominators at the end — never average per-slice ratios.
  • Zero-result guard (errors over silent fallbacks). If a window spans >1 day and a pull returns empty / $0 across the whole window, treat it as suspect (almost certainly a date-range-cap truncation or auth/clock-skew failure, not real zero), surface a warning, and re-pull in ≤7-day chunks before trusting any number. A genuine multi-day $0 on a live account is implausible and looks identical to a capped/empty payload — flag, do not report. (Origin: issue #20 — a 30-day advertiser window returned $0 while a 7-day subset returned ~$12.5K.)
  • Publisher history ~60 days; advertiser lookback ~6 months.
  • Publisher pagination capped at limit=10000 — page through larger result sets.
  • Publisher sign valid only within ±300s of server time.

Three rules, expanded in references/target-roas-tuning-playbook.md:

  • The offer is the unit. Per-geo goals are overrides inside an offer and budget is per offer, so evaluate the offer envelope first, keep the cooldown per offer, and make one change per offer per cycle.
  • Size the step by subtracting measured noise first, then take about a quarter of what is left: 2 to 7% of the goal in practice, floored at 2% and never above the vendor’s 10% ceiling.
  • Watch a fresh regression for 2 to 3 days before acting (2 to lower, 3 to raise), unless spend pace demands a cap cut, which is the fast lever while the goal is the slow one.
time = unixSeconds()
sign = md5(SECRET + md5(time))
GET https://api.mintegral.com/reporting/v2/data
?skey=<skey>&sign=<sign>&time=<time>
&start=20260525&end=20260531
&group_by=date,app_id,placement_id
&timezone=8&limit=10000&page=1
→ JSON rows: { date, app_id, placement_id, est_revenue, ecpm, impression, fill_rate, ... }
ts = unixSeconds()
token = md5(api_key + md5(ts))
# Step 1 — trigger/poll
GET https://ss-api.mintegral.com/api/v2/reports/data
?start_time=2026-05-25&end_time=2026-05-31
&dimension_option=Campaign,Creative,Location&type=1
Headers: access-key, token, timestamp
→ poll until code 200
# Step 2 — download
GET .../api/v2/reports/data?...&type=2 → TSV stream → parse rows

Generate the correct token for the surface (advertiser md5(api_key+md5(ts)) header OR publisher md5(SECRET+md5(time)) query), issue a minimal request, and confirm HTTP code + clock skew (publisher ±300s window).

  • Nested MD5, not HMAC. Mintegral labels the credential “token”/“HMAC” but it is md5(key + md5(timestamp)). Do NOT use crypto HMAC libs.
  • Two separate auth schemes & hosts. Header-based (advertiser, ss-api.mintegral.com) vs query-param (publisher, api.mintegral.com). Don’t mix them.
  • Advertiser report is ASYNC. Poll type=1 until code 200, THEN call type=2 to download. Calling type=2 early returns nothing.
  • Advertiser type=2 returns TAB-separated text, not JSON — parse as TSV. The publisher report returns JSON.
  • Publisher sign has a ±300-second window. Server clock skew causes auth failure — sync time / retry.
  • Data latency ~1.5h after day close; generated advertiser files retained only 1 month.
  • est_revenue is estimated, not finalized — reconcile against payment statements.
  • No documented rate limits. Implement client-side throttling / exponential backoff defensively.
  • Lowering the max-delta cap also raises the goal floor. The relative floor is baseTargetGoal - maxDelta, so “make it gentler” by cutting the cap silently suppresses lower-goal proposals instead of shrinking them. Keep the cap at the vendor’s 10% and change the gain (references/target-roas-tuning-playbook.md section 4).
  • A 7-day review must judge on D0, not D7. D7 needs 8 complete days of maturity before a cohort date counts, so inside a 7-day window every D7 figure is immature and reads far too low.
  • No SKAN-dedicated endpoint. SKAN surfaces inside standard report dimensions with null privacy-thresholded values; postbacks are delayed (no real-time SKAN).

Endpoint-level detail (params, response fields, MCP tool mapping) lives in references/:

  • references/mintegral-publisher-api.md — publisher/monetization reporting endpoint + signature algorithm.
  • references/mintegral-ua-campaign-report-api.md — UA campaign, performance-report (v1/v2), and event endpoints.
  • references/mintegral-ua-offers-api.md — UA offer endpoints + auth. Read-only reference: mutate via the MCP, never hand-rolled.
  • references/mcp-api-families.md — the MCP’s three API families (Advertiser / Developer / Publisher), per-family auth env vars, the full 17-tool → endpoint map, and the two-gate write model. Note the Developer family (dev.mintegral.com, apps/placements/units) is a third surface not covered by the two reporting surfaces above.
  • references/mcp-playbooks.md — copy-ready guarded-write playbooks.
  • references/target-roas-tuning-playbook.md: Target-ROAS goal tuning, vendor step/frequency limits, noise-subtracted step sizing, the persistence gate, budget as a guardrail, and a manual weekly routine.

Upstream docs: