Pull the same metrics you see in the dashboard — revenue, impressions, placements, devices, geography, user insights — from scripts, cron jobs, or custom integrations. All endpoints are read-only.
Base URL
https://platform.trygravity.ai
Authentication
Every request must include your Gravity API key in the X-API-Key header. Grab the key from your dashboard under Settings → Platform Settings.
curl https://platform.trygravity.ai/publisher-dashboard/info \
-H "X-API-Key: YOUR_API_KEY"
This is the same API key used to serve ads. No extra credentials required.
Endpoints
GET /publisher-dashboard/info
Publisher profile and lifetime totals.
curl https://platform.trygravity.ai/publisher-dashboard/info \
-H "X-API-Key: YOUR_API_KEY"
{
"publisher_id": "abc-123",
"name": "My Platform",
"url": "https://myplatform.com",
"payout_model": "CPM",
"total_impressions": 7800000,
"total_clicks": 42000
}
GET /publisher-dashboard/stats
Daily performance time series — impressions, clicks, revenue, CPM, CPC, CTR.
Number of days to look back (1–3650).
Start date (YYYY-MM-DD). Overrides days when paired with end_date.
IANA timezone for date bucketing (e.g. America/New_York).
curl "https://platform.trygravity.ai/publisher-dashboard/stats?days=7&tz=America/New_York" \
-H "X-API-Key: YOUR_API_KEY"
{
"totalImpressions": 250000,
"totalClicks": 1200,
"totalRevenue": 1250.50,
"avgCpm": 5.00,
"avgCpc": 1.04,
"avgCtr": 0.48,
"timeSeries": [
{
"date": "2025-05-20",
"impressions": 35000,
"clicks": 170,
"revenue": 178.50,
"cpm": 5.10,
"cpc": 1.05,
"ctr": 0.49
}
]
}
GET /publisher-dashboard/activity
Ad request funnel — requests, wins, impressions, fill rate, show rate.
curl "https://platform.trygravity.ai/publisher-dashboard/activity?days=7" \
-H "X-API-Key: YOUR_API_KEY"
{
"data": [
{
"date": "2025-05-20",
"requests": 50000,
"wins": 35000,
"impressions": 30000,
"revenue": 150.25
}
],
"total_requests": 350000,
"total_wins": 245000,
"total_impressions": 210000,
"total_revenue": 1050.00,
"fill_rate": 0.70,
"show_rate": 0.8571
}
| Field | Description |
|---|
fill_rate | wins / requests — how often a campaign matched. |
show_rate | impressions / wins — how often matched ads were viewed. |
GET /publisher-dashboard/placements
Per-placement performance breakdown with daily time series.
curl "https://platform.trygravity.ai/publisher-dashboard/placements?days=7" \
-H "X-API-Key: YOUR_API_KEY"
{
"placements": [
{
"placement": "below_response",
"impressions": 120000,
"clicks": 600,
"ctr": 0.005,
"revenue": 600.00,
"cpm": 5.00,
"cpc": 1.00,
"daily": [
{
"date": "2025-05-20",
"impressions": 17000,
"clicks": 85,
"ctr": 0.005,
"revenue": 85.00,
"cpm": 5.00,
"cpc": 1.00
}
]
}
],
"period_days": 7
}
GET /publisher-dashboard/devices
Performance breakdown by device type (desktop, mobile, tablet).
curl "https://platform.trygravity.ai/publisher-dashboard/devices?days=30" \
-H "X-API-Key: YOUR_API_KEY"
{
"devices": [
{
"device_type": "desktop",
"impressions": 150000,
"clicks": 750,
"ctr": 0.005,
"revenue": 750.00,
"cpm": 5.00,
"cpc": 1.00,
"daily": [
{
"date": "2025-05-20",
"device_type": "desktop",
"impressions": 5000,
"clicks": 25,
"ctr": 0.005,
"revenue": 25.00,
"cpm": 5.00,
"cpc": 1.00
}
]
}
],
"period_days": 30
}
GET /publisher-dashboard/geography
Per-country performance breakdown.
curl "https://platform.trygravity.ai/publisher-dashboard/geography?days=30" \
-H "X-API-Key: YOUR_API_KEY"
{
"countries": [
{
"country_code": "US",
"impressions": 500000,
"clicks": 2500,
"ctr": 0.005,
"revenue": 2500.00,
"cpm": 5.00,
"cpc": 1.00
}
],
"period_days": 30
}
GET /publisher-dashboard/user-insights
User engagement analytics — summary stats, daily unique users, retention/saturation/CTR distributions.
curl "https://platform.trygravity.ai/publisher-dashboard/user-insights?days=30" \
-H "X-API-Key: YOUR_API_KEY"
{
"summary": {
"total_unique_users": 12000,
"avg_daily_users": 400.0,
"avg_ads_per_user": 3.2,
"avg_ctr": 1.50,
"repeat_user_rate": 35.0
},
"daily": [
{ "date": "2025-05-20", "unique_users": 420 }
],
"retention": [
{ "bucket": "1 day", "count": 7800, "percentage": 65.0 },
{ "bucket": "2-5 days", "count": 2400, "percentage": 20.0 }
],
"ad_saturation": [
{ "bucket": "1-5", "count": 9000, "percentage": 75.0 }
],
"ctr_distribution": [
{ "bucket": "0%", "count": 6000, "percentage": 50.0 },
{ "bucket": "<2%", "count": 3600, "percentage": 30.0 }
]
}
GET /publisher-dashboard/users
Paginated per-user lifetime stats with sorting and search.
Page number (starts at 1).
Results per page (1–200).
Sort column. One of: requests, ads_served, impressions, clicks, revenue_microdollars, first_seen, last_seen.
Sort direction: asc or desc.
Filter users by ID (partial match).
curl "https://platform.trygravity.ai/publisher-dashboard/users?page=1&per_page=10&sort=impressions&order=desc" \
-H "X-API-Key: YOUR_API_KEY"
{
"users": [
{
"pub_user_id": "user_abc123",
"requests": 500,
"ads_served": 350,
"impressions": 300,
"clicks": 15,
"revenue_microdollars": 1500000,
"first_seen": "2025-01-15",
"last_seen": "2025-05-20"
}
],
"total": 12000,
"has_more": true,
"page": 1,
"per_page": 10
}
GET /publisher-dashboard/countries
Top countries by user count.
Number of countries to return (1–100).
curl "https://platform.trygravity.ai/publisher-dashboard/countries?limit=10" \
-H "X-API-Key: YOUR_API_KEY"
{
"countries": [
{
"country_code": "US",
"requests": 200000,
"ads_served": 140000,
"unique_users": 8000,
"pct_requests": 57.1
}
]
}
Code examples
import requests
API_KEY = "your-api-key"
BASE = "https://platform.trygravity.ai/publisher-dashboard"
# Get last 30 days of performance stats
stats = requests.get(
f"{BASE}/stats",
headers={"X-API-Key": API_KEY},
params={"days": 30, "tz": "America/New_York"},
).json()
print(f"Impressions: {stats['totalImpressions']:,}")
print(f"Revenue: ${stats['totalRevenue']:.2f}")
print(f"eCPM: ${stats['avgCpm']:.2f}")
Errors
| Status | Description |
|---|
401 | Invalid or missing X-API-Key. |
400 | Invalid parameter (e.g. bad timezone, out-of-range days). |
422 | Missing required parameter. |
Questions
Email support@trygravity.ai for anything API-related. We read it. 
