Base URL
Authentication
Send your API key in theX-API-Key header on every request. You’ll find the key in the Gravity dashboard under Settings → Organization. Only an owner or admin of the organization can see it.
List your campaigns
status (active, paused, or draft), or leave it off to get every campaign.
delivery_status tells you whether a campaign can serve right now. When delivery is limited or blocked, delivery_issues gives the reason, for example ad_image_required.
Read a performance report
GET /advertiser-dashboard/metrics returns one row per day and the totals for the range.
days (1 to 365) to look back from today, or start_date and end_date (YYYY-MM-DD) for a fixed range. Add campaign_id to report on one campaign.
Set tz to your ad account’s reporting time zone so daily rows match the Gravity dashboard. Use the same time zone for each comparison.
Create and launch a campaign
Set up conversion tracking first, and confirm that Events Manager shows a server event for the conversion you optimize for. Then create the campaign as a draft, so nothing spends while you check it. Use theconversions objective with that event as conversion_type, unless the advertiser asks for clicks or reach. A campaign needs at least one ad group. A generative group writes its own ads from your context. A manual group serves the ads you write.
201 with the new campaign, including its campaign_id and ad groups. Users see brand_name next to the ad, so set it to the brand you advertise, not an internal account label.
When the campaign looks right, launch it:
- Your billing is ready. If not, you get
402. - At least one ad group isn’t paused. If all are paused, you get
409. - A conversion campaign has received a CAPI event for its result event. If not, you get
409. See Server-side conversions.
Change a budget
Send only the fields you want to change:daily_budget is an average in dollars. Spend on one day (UTC) can reach 110% of the daily budget. Then the campaign stops serving until the next day. A campaign with "budget_type": "total" uses total_budget instead, and a target_cpa campaign can also set a monthly_budget. A budget change can move the campaign to Gravity-only delivery.
Pause, resume, or archive a campaign
To pause, send{"status": "paused"} to PATCH /advertiser-dashboard/campaigns/{campaign_id}. Send {"status": "active"} to resume, with the same checks as a launch.
To archive, call PATCH /advertiser-dashboard/campaigns/{campaign_id}/archive. Each call flips the archived state. Archiving also pauses the campaign, and a restored campaign stays paused until you set it to active.
Target regions or customer lists
To target regions or DMAs, look up their location IDs and send them in the campaign’sgeo_targets field:
POST /advertiser-dashboard/audiences/custom-list. For eligible campaigns, send the list IDs in include_audience_ids or exclude_audience_ids. See Targeting.
Add a conversion pixel
is_functional starts as null and changes to true or false once the check runs. To send conversions that your backend confirms, use the Conversions API.
Errors
Errors come back as JSON with adetail field. The most common are 401 (the key isn’t valid), 402 (billing blocks activation), 404 (the object isn’t in your account), 409 (a conflict, for example all ad groups of the campaign are paused), and 422 (the request isn’t valid, including a missing X-API-Key header). The reference lists every status and cause.
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, for example create and launch campaigns.
The agent gets full admin access and actions run without confirmation. For setup, tools, and safety notes, see Dashboard MCP server.