Base URL
Authentication
Send your Gravity API key in theX-API-Key header on every request. To find it, open Settings in the dashboard and copy the key from the API Key card. It’s the same key you use to request ads.
Read your earnings
GET /publisher-dashboard/stats returns a daily series of impressions, clicks, revenue, CPM, CPC, and CTR, plus totals. The numbers match the Overview and Earnings pages of the dashboard.
days to look back from today, or start_date and end_date (YYYY-MM-DD) for a fixed range. A date range replaces days. Set tz to the IANA time zone you want the daily buckets in. The default is UTC.
Break down your results
If Gravity has turned on the user value API for your account, you can also rank your users by usage and value and look up one user’s group. See Users and segments.
Each endpoint has its own range limit for
days. The reference lists them.
Create a placement
A placement is an ad slot. You can create one without opening the dashboard:201 with the new placement. Its slug (here Sidebar-Slot) is the placement_id you send in ad requests. The placement starts as active, but Gravity refreshes its placement cache every 5 minutes, so ad requests get no ad for the new slot until the next refresh.
Gravity builds the slug from name, and the slug must be unique in your account. A duplicate returns 409.
Errors
A missing or invalid key returns401. A bad parameter, such as an unknown time zone or a date range that’s too long, returns 400. A request that fails validation returns 422. The reference lists every status.
MCP server
An AI agent can use this API through the dashboard MCP server athttps://platform.trygravity.com/mcp. The server uses the same API key, so an agent can read reports and also act in the dashboard.
The agent gets full admin access and actions run without confirmation. For setup, tools, and safety notes, see Dashboard MCP server.