Get your first report
1
Get your platform API key
Complete platform onboarding, then open
API Keys in the AdMesh dashboard.
Use your existing platform API key or generate one there.
- Use a production key for live performance and earnings.
- Use a test key for test activity. Test earnings require recorded test accounting and may be unavailable until those records exist.
Authorization header as Bearer YOUR_API_KEY.
The key identifies your platform, so you do not need to supply an agent ID.
Make reporting requests from your backend using your existing secret storage.2
Choose a time period
Set the
time_range query parameter to one of these values:today follows your platform reporting timezone, defaulting to UTC.
Rolling windows use UTC and end at the last completed reporting minute.
The returned start_at, end_at, and timezone describe the actual period.3
Request your numbers
Replace These examples use Python 3, Node.js 18+, Java 11+, or Go 1.16+ and their
standard HTTP libraries; no AdMesh SDK is required. Change Completed empty periods return zero counts and earnings. For
YOUR_API_KEY with your platform’s key. This example requests the
last seven days:7d to any of the
supported periods. The examples print the JSON response so you can choose
which fields to display in your dashboard.For HTTP 202, wait for the Retry-After interval before requesting the
report again. That response contains preparation metadata, not metric totals.
The cURL example includes response headers so you can read this interval.A completed response contains totals and the selected period:all,
start_at is null. During initial preparation, HTTP 202 returns metadata
only, with status: "preparing" and Retry-After: 60. Retry after that interval;
missing numbers do not mean zero activity.4
Display earnings and performance
Read Change
exposures, clicks, engagements, and conversions directly.
Divide earnings_micros by 1,000,000 to display earnings in USD:time_range and make another request when a user selects a different
period in your dashboard.What the numbers mean
Earnings can include unsettled amounts. They represent performance earnings,
not your withdrawable balance or a payout statement. See Payouts
to set up your bank details and track payments.
Report freshness and earnings completeness
status is preparing, ready, or stale. After preparation, the API retains
the last completed report if processing fails. Reports more than two minutes
behind the processing cutoff are marked stale. Check processed_through and
updated_at before displaying the numbers as current.
earnings_coverage is independently complete, partial, or unavailable.
A ready report can have incomplete earnings. Check
pending_earnings_recommendations for activity awaiting accounting records and
earnings_excluded_recommendations for foreign or unresolved currency.
accounting_review_required flags accounting rows that cannot be attributed.
accounting_reconciled_through is the accounting reconciliation watermark, or
null if no completed reconciliation is known. Earnings coverage also remains
partial or unavailable while accounting reconciliation is behind the reporting
cutoff. Do not interpret missing earnings as a verified zero.
Set your reporting timezone
Your platform owner can set an IANA timezone through the existing onboarding settings endpoint. This settings request uses the owner’s signed-in Firebase ID token, while reporting requests continue to use the platform API key.How periods and counts work
The time filter uses recommendation creation time. Later clicks, engagements, or conversions update the period in which the recommendation was created. Historical totals can therefore change as those outcomes arrive. Each recommendation counts once at its highest engagement status. These are recommendation counts, not counts of individual event callbacks. The combinedclicks definition is not a count of billable CPC events and never controls
settlement. For example, a
converted recommendation counts as an exposure, click, and conversion; it is no
longer counted as an engagement even if it was engaged earlier.
The API returns only totals. time_range is the only supported query parameter;
custom dates, other agent IDs, traffic overrides, and recommendation lists are
not supported. Your production key reports live traffic only, while your test
key reports test traffic only.
Troubleshooting
Need help? Contact support@useadmesh.com.