Skip to main content
The Dashboard API gives you the data and controls of the advertiser dashboard over REST. Use it to pull reports into your own tools, run scheduled jobs, or create and change campaigns from a script. This page walks through the common tasks. For every endpoint, parameter, response field, and error, see the Advertiser Dashboard API reference.

Base URL

Authentication

Send your API key in the X-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.
The key has full access to your account, including spend. Keep it on your server.
Your account has one key, shared by the Dashboard API, the Conversions API, MMP postbacks, and the dashboard MCP server. An owner or admin can rotate it in Settings → Organization. The Dashboard API and the MCP server refuse the old key at once. Conversion endpoints can accept it for up to about a minute. See Authentication.

List your campaigns

Each campaign comes back with its settings and lifetime impressions, clicks, spend, and conversions. Filter with 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.
Use 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.
Other reports use the same date and time zone parameters:

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 the conversions 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.
The response is 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:
Before Gravity activates the campaign, it checks that:
  • 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.
Activation can send the campaign to review again.

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’s geo_targets field:
Upload a CSV of emails or phone numbers with 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

Gravity checks the installation in the background. 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 a detail 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 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, 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.

Questions

Email support@trygravity.com with any API question.