Skip to main content
Use the reporting API to bring AdMesh performance numbers into your own dashboard or reporting workflow. Each request returns totals for your platform over the selected period. Reports are published in the background approximately once a minute; the response includes the actual processed cutoff.

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.
Send the key in the 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 YOUR_API_KEY with your platform’s key. This example requests the last seven days:
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 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:
Completed empty periods return zero counts and earnings. For 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 exposures, clicks, engagements, and conversions directly. Divide earnings_micros by 1,000,000 to display earnings in USD:
Change 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.
The change appears in the next completed report. Today respects local daylight saving transitions; rolling 1/7/30/90-day windows remain UTC durations.

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 combined clicks 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.