Dashboard API

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.

string

required

Your Gravity API key.

curl https://platform.trygravity.ai/publisher-dashboard/info \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "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.

integer

default:"30"

Number of days to look back (1–3650).

string

Start date (YYYY-MM-DD). Overrides days when paired with end_date.

string

End date (YYYY-MM-DD).

string

default:"UTC"

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"

Response

{
  "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.

integer

default:"7"

Number of days (1–30).

string

Start date (YYYY-MM-DD).

string

End date (YYYY-MM-DD).

string

default:"UTC"

IANA timezone.

curl "https://platform.trygravity.ai/publisher-dashboard/activity?days=7" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "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.

integer

default:"7"

Number of days (1–365).

string

Start date (YYYY-MM-DD).

string

End date (YYYY-MM-DD).

curl "https://platform.trygravity.ai/publisher-dashboard/placements?days=7" \
  -H "X-API-Key: YOUR_API_KEY"

Response

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

integer

default:"30"

Number of days (1–365).

string

Start date (YYYY-MM-DD).

string

End date (YYYY-MM-DD).

curl "https://platform.trygravity.ai/publisher-dashboard/devices?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "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.

integer

default:"30"

Number of days (1–365).

string

Start date (YYYY-MM-DD).

string

End date (YYYY-MM-DD).

curl "https://platform.trygravity.ai/publisher-dashboard/geography?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "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/users`

Paginated per-user lifetime stats with sorting and search.

integer

default:"1"

Page number (starts at 1).

integer

default:"50"

Results per page (1–200).

string

default:"requests"

Sort column. One of: requests, ads_served, impressions, clicks, revenue_microdollars, first_seen, last_seen.

string

default:"desc"

Sort direction: asc or desc.

string

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"

Response

{
  "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.

integer

default:"20"

Number of countries to return (1–100).

curl "https://platform.trygravity.ai/publisher-dashboard/countries?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "countries": [
    {
      "country_code": "US",
      "requests": 200000,
      "ads_served": 140000,
      "unique_users": 8000,
      "pct_requests": 57.1
    }
  ]
}

MCP server

The reporting endpoints above are also exposed as an MCP server, so AI agents and MCP-capable clients can query your account directly.

Endpoint: POST https://platform.trygravity.ai/mcp (JSON-RPC 2.0 over HTTP)
Auth: X-API-Key header (or Authorization: Bearer <key>)

A publisher API key unlocks read-only tools mirroring this API: publisher_get_info, publisher_get_stats, publisher_get_activity, publisher_get_placements, publisher_get_devices, publisher_get_geography, publisher_get_users, and publisher_get_countries.

curl https://platform.trygravity.ai/mcp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

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}")

const API_KEY = "your-api-key";
const BASE = "https://platform.trygravity.ai/publisher-dashboard";

const res = await fetch(`${BASE}/stats?days=30&tz=America/New_York`, {
  headers: { "X-API-Key": API_KEY },
});
const stats = await res.json();

console.log(`Impressions: ${stats.totalImpressions.toLocaleString()}`);
console.log(`Revenue: $${stats.totalRevenue.toFixed(2)}`);
console.log(`eCPM: $${stats.avgCpm.toFixed(2)}`);

# Get publisher info
curl https://platform.trygravity.ai/publisher-dashboard/info \
  -H "X-API-Key: YOUR_API_KEY"

# Get stats for a specific date range
curl "https://platform.trygravity.ai/publisher-dashboard/stats?start_date=2025-05-01&end_date=2025-05-31" \
  -H "X-API-Key: YOUR_API_KEY"

# Get placement breakdown
curl "https://platform.trygravity.ai/publisher-dashboard/placements?days=7" \
  -H "X-API-Key: YOUR_API_KEY"

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.

Get started

Integrate

Optimize

Reference

Base URL

Authentication

Endpoints

GET `/publisher-dashboard/info`

GET `/publisher-dashboard/stats`

GET `/publisher-dashboard/activity`

GET `/publisher-dashboard/placements`

GET `/publisher-dashboard/devices`

GET `/publisher-dashboard/geography`

GET `/publisher-dashboard/users`

GET `/publisher-dashboard/countries`

MCP server

Code examples

Errors

Questions

​Base URL

​Authentication

​Endpoints

​GET /publisher-dashboard/info

​GET /publisher-dashboard/stats

​GET /publisher-dashboard/activity

​GET /publisher-dashboard/placements

​GET /publisher-dashboard/devices

​GET /publisher-dashboard/geography

​GET /publisher-dashboard/users

​GET /publisher-dashboard/countries

​MCP server

​Code examples

​Errors

​Questions

Base URL

Authentication

Endpoints

GET `/publisher-dashboard/info`

GET `/publisher-dashboard/stats`

GET `/publisher-dashboard/activity`

GET `/publisher-dashboard/placements`

GET `/publisher-dashboard/devices`

GET `/publisher-dashboard/geography`

GET `/publisher-dashboard/users`

GET `/publisher-dashboard/countries`

MCP server

Code examples

Errors

Questions