Skip to content
T1KTheOneKit

t1k:marketing:monetization:mintegral

FieldValue
Modulemonetization
Version1.16.9
Efforthigh
Tools—

How to invoke

Section titled “How to invoke”
/t1k:marketing:monetization:mintegral

Mintegral

Section titled “Mintegral”

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

When to Use

Section titled “When to Use”
  • 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

Overview — Two API Surfaces

Section titled “Overview — Two API Surfaces”

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.

Authentication

Section titled “Authentication”

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.

Advertiser (header scheme)

Section titled “Advertiser (header scheme)”

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.

Publisher (query-param scheme)

Section titled “Publisher (query-param scheme)”

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.

Base URLs

Section titled “Base URLs”
  • 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).

Advertiser Performance Reporting

Section titled “Advertiser Performance Reporting”

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.

SKAdNetwork Handling

Section titled “SKAdNetwork Handling”

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.

Date-Range & Pagination Limits

Section titled “Date-Range & Pagination Limits”
  • 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.

Worked Examples

Section titled “Worked Examples”

Revenue dashboard pull (publisher)

Section titled “Revenue dashboard pull (publisher)”
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, ... }

UA cost breakdown (advertiser)

Section titled “UA cost breakdown (advertiser)”
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

Credential validation

Section titled “Credential validation”

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).

Gotchas

Section titled “Gotchas”
  • 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.
  • Max 7-day span per request (both surfaces) — and the advertiser surface enforces it silently: a >7-day window returns empty/$0 with no error, not a clear failure. Chunk-and-sum longer ranges and zero-guard empty multi-day results (see “Date-Range & Pagination Limits”, issue #20). Publisher ~60-day history, advertiser ~6-month lookback.
  • 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.
  • No SKAN-dedicated endpoint. SKAN surfaces inside standard report dimensions with null privacy-thresholded values; postbacks are delayed (no real-time SKAN).

References

Section titled “References”

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

Upstream docs: