Skip to main content
The Dashboard API gives you the numbers from your publisher dashboard over REST: revenue, impressions, placements, devices, and geography. Use it from scripts, scheduled jobs, or your own tools. The reporting endpoints are read-only, and one endpoint creates placements. This page walks through the common tasks. For every endpoint, parameter, response field, and error, see the Publisher Dashboard API reference.

Base URL

Authentication

Send your Gravity API key in the X-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.
The key has full access to your publisher account. Keep it on your server.
Your account has one key, shared by ad requests, the Dashboard API, and the dashboard MCP server. Rotating it (Rotate on the API Key card in Settings) stops the old key on the Dashboard API and the MCP server at once. Ad requests can take a few minutes to change over to the new key.

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.
Use 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:
The response is 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 returns 401. 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 at https://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.

Questions

Email support@trygravity.com with any API question.