Dashboard API - Gravity

Pull the same metrics you see in the advertiser dashboard — and create, update, and archive campaigns and ad units — from scripts, cron jobs, or custom integrations.

Base URL

https://platform.trygravity.ai

Authentication

Every request must include your Gravity advertiser API key in the X-API-Key header. Grab the key from your dashboard under Settings → API Key.

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

This is the same API key shown on your advertiser settings page. You can regenerate it at any time.

Endpoints

GET `/advertiser-dashboard/info`

Advertiser profile.

string

required

Your advertiser API key.

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

Response

{
  "advertiser_id": "abc-123",
  "name": "Acme Corp",
  "email": "ads@acme.com"
}

GET `/advertiser-dashboard/campaigns`

List all campaigns with lifetime stats (impressions, clicks, spend, conversions).

string

Filter by campaign status (e.g. active, paused, draft).

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

Response

{
  "campaigns": [
    {
      "campaign_id": "camp-456",
      "name": "Summer Sale",
      "status": "active",
      "is_active": true,
      "daily_budget": 100.0,
      "landing_page": "https://acme.com/summer",
      "campaign_objective": "conversions",
      "created_at": "2025-05-01T00:00:00",
      "start_time": "2025-05-01T00:00:00",
      "end_time": null,
      "impressions": 350000,
      "clicks": 1800,
      "spend": 875.50,
      "conversions": 42,
      "conversion_value": 4200.00
    }
  ]
}

GET `/advertiser-dashboard/campaigns/{campaign_id}`

Single campaign detail with full stats and targeting config.

string

required

The campaign ID.

curl "https://platform.trygravity.ai/advertiser-dashboard/campaigns/camp-456" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "campaign_id": "camp-456",
  "name": "Summer Sale",
  "status": "active",
  "is_active": true,
  "daily_budget": 100.0,
  "landing_page": "https://acme.com/summer",
  "campaign_objective": "conversions",
  "created_at": "2025-05-01T00:00:00",
  "start_time": "2025-05-01T00:00:00",
  "end_time": null,
  "allowed_countries": ["US", "CA"],
  "allowed_devices": ["desktop", "mobile"],
  "utm_params": { "utm_source": "gravity", "utm_medium": "ai" },
  "deployment_status": "deployed",
  "impressions": 350000,
  "clicks": 1800,
  "spend": 875.50,
  "conversions": 42,
  "conversion_value": 4200.00
}

GET `/advertiser-dashboard/metrics`

Daily time-series performance metrics.

integer

default:"30"

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

string

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

string

End date (YYYY-MM-DD).

string

Filter to a single campaign. Omit for aggregate metrics across all campaigns.

string

default:"UTC"

IANA timezone (e.g. America/New_York) used to bucket days. Defaults to UTC. Set this to your ad account’s reporting timezone so daily rows line up with the Gravity Dashboard and, for ChatGPT/OpenAI campaigns, with OpenAI’s reporting (OpenAI ad accounts currently report in America/New_York).

Days are bucketed by the timezone you pass in tz, not the timezone of the machine calling the API. A calendar day in UTC and the same day in America/New_York cover different hours, so the totals will differ — pick one timezone and use it consistently as your source of truth.

curl "https://platform.trygravity.ai/advertiser-dashboard/metrics?days=7&tz=America/New_York" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "date": "2025-05-20",
      "impressions": 50000,
      "clicks": 260,
      "spend": 125.00,
      "conversions": 6,
      "revenue": 600.00,
      "ctr": 0.52,
      "cpc": 0.48,
      "cpm": 2.50,
      "conversion_rate": 2.31,
      "cpa": 20.83,
      "roas": 4.80
    }
  ],
  "total_impressions": 350000,
  "total_clicks": 1800,
  "total_spend": 875.50,
  "total_conversions": 42,
  "total_revenue": 4200.00
}

Metric	Description
`ctr`	Click-through rate (clicks / impressions × 100).
`cpc`	Cost per click (spend / clicks).
`cpm`	Cost per mille (spend / impressions × 1000).
`conversion_rate`	Conversions / clicks × 100.
`cpa`	Cost per acquisition (spend / conversions).
`roas`	Return on ad spend (revenue / spend).

GET `/advertiser-dashboard/ad-unit-metrics`

Daily time-series metrics broken down per ad unit — the same numbers shown under Ad units on a campaign’s detail page. Use this for creative-level reporting and optimization, where campaign-level /metrics isn’t granular enough. Returns one series per (campaign, ad unit) link, each tagged with a data_source. Series built from real per-ad-unit stats are "ad_unit_stats". A campaign with a single linked ad unit and no per-ad-unit rows yet falls back to the campaign’s own daily totals (data_source: "campaign_fallback") so the numbers stay consistent with the dashboard.

This endpoint reports impressions, clicks, spend, CTR, CPC, and CPM per ad unit. Conversions/CPA/ROAS are attributed at the campaign level — use /metrics or /conversions for those.

integer

default:"30"

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

string

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

string

End date (YYYY-MM-DD).

string

Filter to a single campaign.

string

Filter to a single ad unit. Returns 404 if the ad unit isn’t found in your account.

string

default:"UTC"

IANA timezone (e.g. America/New_York) used to bucket days. Same behavior as /metrics — set it to your ad account’s reporting timezone.

curl "https://platform.trygravity.ai/advertiser-dashboard/ad-unit-metrics?days=7&campaign_id=camp-456&tz=America/New_York" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "ad_units": [
    {
      "ad_unit_id": "ad-123",
      "campaign_id": "camp-456",
      "name": "Character & Brand Voice",
      "data_source": "ad_unit_stats",
      "total_impressions": 19784,
      "total_clicks": 131,
      "total_spend": 88.20,
      "data": [
        {
          "date": "2025-05-20",
          "impressions": 3200,
          "clicks": 22,
          "spend": 14.60,
          "ctr": 0.69,
          "cpc": 0.66,
          "cpm": 4.56
        }
      ]
    }
  ]
}

Field	Description
`data_source`	`ad_unit_stats` for real per-ad-unit rows, or `campaign_fallback` when a single-ad-unit campaign inherits campaign-level daily totals.
`total_impressions` / `total_clicks` / `total_spend`	Series totals over the requested range.
`data[].ctr`	Click-through rate (clicks / impressions × 100).
`data[].cpc`	Cost per click (spend / clicks).
`data[].cpm`	Cost per mille (spend / impressions × 1000).

GET `/advertiser-dashboard/conversions`

Recent conversions with pagination. Returns attributed and unattributed conversions.

integer

default:"50"

Page size (1–100).

string

Opaque pagination cursor (pass next_cursor from a previous response).

string

Filter to a single campaign.

string

Filter by conversion event type (e.g. purchase, lead).

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

Response

{
  "conversions": [
    {
      "conversion_id": "conv-789",
      "event_type": "purchase",
      "value_cents": 9999,
      "currency": "USD",
      "conversion_timestamp": "2025-05-20T14:30:00",
      "campaign_id": "camp-456",
      "order_id": "order-abc",
      "page_url": "https://acme.com/checkout/success",
      "source": "capi",
      "is_attributed": true
    }
  ],
  "total_conversions": 42,
  "has_more": true,
  "next_cursor": "conv-788"
}

GET `/advertiser-dashboard/billing`

Billing summary — total spend, billed, unbilled, credits.

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

Response

{
  "total_spend_dollars": 875.50,
  "total_billed_dollars": 800.00,
  "unbilled_dollars": 75.50,
  "credits_dollars": 0.00,
  "billing_enabled": true,
  "last_spend_sync_at": "2025-05-20T15:00:00",
  "last_billed_at": "2025-05-19T00:00:00"
}

GET `/advertiser-dashboard/events/analytics`

Pixel event analytics — domain breakdowns, time-series, and event type counts from your tracking pixel.

integer

default:"30"

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

string

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

string

End date (YYYY-MM-DD).

string

Filter by domain (partial match).

string

Filter by event type (e.g. page_view, form_submit, click).

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

Response

{
  "domains": [
    { "domain": "acme.com", "events": 12500 },
    { "domain": "blog.acme.com", "events": 3200 }
  ],
  "time_series": [
    { "date": "2025-05-20T00:00:00", "events": 850 },
    { "date": "2025-05-20T01:00:00", "events": 720 }
  ],
  "event_types": [
    { "event_type": "page_view", "total": 10000, "last_received": "2025-05-20T15:00:00" },
    { "event_type": "form_submit", "total": 500, "last_received": "2025-05-20T14:30:00" }
  ],
  "has_historical_data": true
}

GET `/advertiser-dashboard/events/conversion-stats`

Conversion time-series from conversion_stats_hourly — daily totals and per-event-type breakdowns.

integer

default:"30"

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

string

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

string

End date (YYYY-MM-DD).

string

Filter by conversion event type (e.g. purchase, lead).

curl "https://platform.trygravity.ai/advertiser-dashboard/events/conversion-stats?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "time_series": [
    { "date": "2025-05-20T00:00:00", "conversions": 8 },
    { "date": "2025-05-21T00:00:00", "conversions": 12 }
  ],
  "total": 42,
  "by_event_type": [
    { "event_type": "purchase", "total": 30 },
    { "event_type": "lead", "total": 12 }
  ]
}

GET `/advertiser-dashboard/integrations`

Connected Shopify stores. See Integrations for how to connect one.

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

Response

{
  "shopify": [
    {
      "id": "conn-123",
      "shop_domain": "acme-store.myshopify.com",
      "is_active": true,
      "connected_at": "2025-04-01T12:00:00",
      "verification_status": "verified"
    }
  ]
}

Managing campaigns

These endpoints let you create, edit, pause, and archive advertiser campaigns from the same API key surface.

POST `/advertiser-dashboard/campaigns`

Create a campaign with inline ad groups (recommended) or legacy ad-unit links.

string

required

Campaign name.

string

required

Destination URL for the campaign.

number

required

Daily budget in dollars.

string

Campaign status. Use draft, active, or paused.

string

Campaign objective.

string

Billing model.

string

Bid strategy.

boolean

Whether the campaign is active.

string

Optional start timestamp.

string

Optional end timestamp.

integer

Optional click goal.

number

Optional max cost-per-click bid in dollars. When set, OpenAI-network ad groups place a fixed per-click bid at this amount (on a conversions-objective campaign this is oCPC: conversion-optimized, billed per click at your bid). When omitted, conversions campaigns use OpenAI’s maximize_conversions auto-bidding — no bid is required — and other objectives use per-impression bidding. 0 is treated as unset.

integer

Optional impression goal.

number

Optional max CPM.

string

Optional conversion type.

number

Optional max CPA.

object

Optional demographics configuration.

array

Optional UTM parameters as key/value pairs.

array

Optional country targeting.

array

Optional device targeting.

object

Optional lead-form configuration.

array

Ad groups to create inline with the campaign. Each entry uses the same shape as POST /advertiser-dashboard/ad-groups minus campaign_id (it is set from the new campaign). Manual groups may include authored ads; generative groups generate their own ads and reject authored ads.

array

Legacy: one or more existing ad-unit IDs to link. Still supported, but ad groups are the current model.

Provide at least one of ad_groups or ad_unit_ids — the router returns 422 if both are missing or empty. Network selection is server-managed and always uses Gravity. keywords is not accepted here, and network_type / network_config return 422 if included.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/campaigns \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale",
    "landing_page": "https://acme.com/summer",
    "daily_budget": 100,
    "status": "active",
    "campaign_objective": "conversions",
    "billing_model": "cpm",
    "bid_strategy": "lowest_cost",
    "allowed_countries": ["US", "CA"],
    "allowed_devices": ["desktop", "mobile"],
    "ad_groups": [
      {
        "name": "Summer Sale — Generative",
        "group_type": "generative",
        "context": "Summer footwear sale, focus on running shoes"
      },
      {
        "name": "Summer Sale — Manual",
        "group_type": "manual",
        "ads": [
          {
            "headline": "50% Off Running Shoes",
            "copy": "Summer sale on all running shoes.",
            "cta": "Shop Now",
            "landing_page": "https://acme.com/summer"
          }
        ]
      }
    ]
  }'

Response

{
  "campaign_id": "camp-456",
  "user_id": "adv-123",
  "name": "Summer Sale",
  "landing_page": "https://acme.com/summer",
  "daily_budget": 100,
  "status": "active",
  "campaign_objective": "conversions",
  "is_active": true,
  "created_at": "2025-05-01T00:00:00",
  "start_time": "2025-05-01T00:00:00",
  "end_time": null,
  "daily_budget_remaining": 87.5,
  "allowed_countries": ["US", "CA"],
  "allowed_devices": ["desktop", "mobile"],
  "utm_params": null,
  "custom_favicon_url": null,
  "deployment_status": "pending_review",
  "review_status": "pending_review",
  "submitted_for_review_at": "2025-05-01T00:00:00",
  "reviewed_at": null,
  "review_notes": null,
  "lead_form_config": null,
  "ad_groups": [
    {
      "id": "adg-789",
      "campaign_id": "camp-456",
      "name": "Summer Sale — Generative",
      "group_type": "generative",
      "status": "active",
      "ads": [],
      "ads_total": 0
    },
    {
      "id": "adg-790",
      "campaign_id": "camp-456",
      "name": "Summer Sale — Manual",
      "group_type": "manual",
      "status": "active",
      "ads": [
        {
          "id": "ad-901",
          "ad_group_id": "adg-790",
          "campaign_id": "camp-456",
          "headline": "50% Off Running Shoes",
          "copy": "Summer sale on all running shoes.",
          "cta": "Shop Now",
          "landing_page": "https://acme.com/summer",
          "source": "manual",
          "status": "active",
          "review_status": "pending"
        }
      ],
      "ads_total": 1
    }
  ]
}

Ad-group response objects also include targeting and budget fields (context, landing_page, daily_budget, max_cpc, allowed_countries, allowed_devices, etc.) — see Managing ad groups & ads.

PATCH `/advertiser-dashboard/campaigns/{campaign_id}`

Edit a campaign or pause/unpause it.

string

required

The campaign ID.

string

Optional campaign name.

string

Optional landing page URL.

number

Optional daily budget.

string

Optional campaign objective.

number

Optional max cost-per-click bid in dollars. When set, OpenAI-network ad groups place a fixed per-click bid at this amount; editing it re-syncs live ad groups with the new bid. Send null (or 0) to clear it — conversions campaigns then use OpenAI’s maximize_conversions auto-bidding.

string

Optional status. Use active, paused, or draft.

string

Optional start timestamp.

string

Optional end timestamp.

array

Optional country targeting.

array

Optional device targeting.

array

Optional UTM parameters as key/value pairs.

string

Optional favicon URL.

object

Optional lead-form configuration.

curl -X PATCH https://platform.trygravity.ai/advertiser-dashboard/campaigns/camp-456 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

Response

{
  "campaign_id": "camp-456",
  "user_id": "adv-123",
  "name": "Summer Sale",
  "landing_page": "https://acme.com/summer",
  "daily_budget": 100,
  "status": "paused",
  "campaign_objective": "conversions",
  "is_active": false,
  "created_at": "2025-05-01T00:00:00",
  "start_time": "2025-05-01T00:00:00",
  "end_time": null,
  "daily_budget_remaining": 87.5,
  "allowed_countries": ["US", "CA"],
  "allowed_devices": ["desktop", "mobile"],
  "utm_params": null,
  "custom_favicon_url": null,
  "deployment_status": "deployed",
  "review_status": "approved",
  "submitted_for_review_at": "2025-05-01T00:00:00",
  "reviewed_at": "2025-05-01T01:00:00",
  "review_notes": null,
  "lead_form_config": null
}

Activating a campaign runs the billing gate and can return 402. Budget or network changes can force the Gravity-only fallback, and activation can resubmit the campaign for review and enqueue background sync.

PATCH `/advertiser-dashboard/campaigns/{campaign_id}/archive`

Toggle a campaign’s archived state.

string

required

The campaign ID.

curl -X PATCH https://platform.trygravity.ai/advertiser-dashboard/campaigns/camp-456/archive \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "campaign_id": "camp-456",
  "is_archived": true
}

Archiving also sets is_active = false and status = "paused".

Managing ad groups & ads

Campaigns are now structured as campaign → ad groups → ads. An ad group is either:

generative (default) — Gravity generates ads for the group from your context / ad_prompt. Authored ads are rejected with 422.
manual — you author the ads yourself via the ads array or the ads endpoints below. Generated ads are read-only; only manual ads can be edited or archived.

These endpoints share the same implementation and ownership checks as the Gravity dashboard, scoped to your API key’s account.

GET `/advertiser-dashboard/ad-groups`

List your ad groups, each with its ads embedded (up to 100 per group; ads_total carries the full count).

string

Filter to a single campaign.

boolean

default:"false"

Include archived groups.

curl "https://platform.trygravity.ai/advertiser-dashboard/ad-groups?campaign_id=camp-456" \
  -H "X-API-Key: YOUR_API_KEY"

Response

[
  {
    "id": "adg-789",
    "campaign_id": "camp-456",
    "name": "Summer Sale — Generative",
    "group_type": "generative",
    "status": "active",
    "context": "Summer footwear sale, focus on running shoes",
    "landing_page": null,
    "daily_budget": null,
    "auto_optimize_budget": true,
    "max_cpc": null,
    "allowed_countries": null,
    "allowed_devices": null,
    "sort_order": 0,
    "created_at": "2026-07-23 00:00:00",
    "updated_at": "2026-07-23 00:00:00",
    "ads": [],
    "ads_total": 0
  }
]

POST `/advertiser-dashboard/ad-groups`

Create an ad group under one of your campaigns.

string

required

The campaign to attach the group to. Must be owned by your account.

string

required

Ad-group name.

string

default:"generative"

generative or manual.

string

default:"active"

active, paused, or archived.

string

Targeting context used to match conversations (and to generate ads for generative groups).

string

Conversations to avoid.

string

Optional prompt guiding ad generation (generative groups).

string

Default landing page for the group’s ads.

integer

Optional group-level daily budget. auto_optimize_budget (default true) lets Gravity allocate budget across groups; min_daily_budget / max_daily_budget bound it.

number

Optional group-level max CPC.

array

Optional country targeting override.

array

Optional device targeting override.

array

Authored ads (manual groups only). Each ad supports name, headline (≤80 chars), copy (≤500 chars), cta (≤80 chars), description, landing_page, image_url, and status.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/ad-groups \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "camp-456",
    "name": "Trail Runners — Manual",
    "group_type": "manual",
    "context": "Trail running gear",
    "ads": [
      {
        "headline": "Grip Every Trail",
        "copy": "Trail shoes built for mud, rock, and rain.",
        "cta": "Shop Trail",
        "landing_page": "https://acme.com/trail"
      }
    ]
  }'

Returns 201 with the created group and its ads (same shape as the list response). 422 if authored ads are sent to a generative group.

GET `/advertiser-dashboard/ad-groups/{ad_group_id}`

Fetch a single ad group with its ads.

PATCH `/advertiser-dashboard/ad-groups/{ad_group_id}`

Update any of the fields above (send only what changes). Converting a manual group to generative returns 422 while it still has live manual ads.

curl -X PATCH https://platform.trygravity.ai/advertiser-dashboard/ad-groups/adg-789 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused", "daily_budget": 50}'

DELETE `/advertiser-dashboard/ad-groups/{ad_group_id}`

Archive an ad group (and its ads). Returns 204.

POST `/advertiser-dashboard/ad-groups/{ad_group_id}/ads`

Author an ad in a manual group. Returns 201 with the created ad; 422 on generative groups.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/ad-groups/adg-790/ads \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "50% Off Running Shoes",
    "copy": "Summer sale on all running shoes.",
    "cta": "Shop Now",
    "landing_page": "https://acme.com/summer"
  }'

Response

{
  "id": "ad-901",
  "ad_group_id": "adg-790",
  "campaign_id": "camp-456",
  "name": null,
  "headline": "50% Off Running Shoes",
  "copy": "Summer sale on all running shoes.",
  "cta": "Shop Now",
  "description": null,
  "landing_page": "https://acme.com/summer",
  "image_url": null,
  "source": "manual",
  "status": "active",
  "review_status": "pending",
  "created_at": "2026-07-23 00:00:00",
  "updated_at": "2026-07-23 00:00:00"
}

PATCH `/advertiser-dashboard/ads/{ad_id}`

Edit a manual ad (headline, copy, cta, landing_page, status, etc.). Generated ads are read-only and return 422.

DELETE `/advertiser-dashboard/ads/{ad_id}`

Archive a manual ad. Returns 204.

Legacy: ad units (deprecated)

Ad units are the legacy creative model. They keep working for existing integrations — nothing breaks — but new integrations should use ad groups & ads instead. Campaigns are now structured as campaign → ad group → ad.

POST `/advertiser-dashboard/ad-units`

Create an ad unit owned by your advertiser account.

string

required

Ad-unit name.

string

Optional headline.

string

required

Required at submit time.

string

required

Required at submit time.

string

required

Required at submit time.

string

required

Required at submit time.

string

Optional favicon URL.

string

Optional image URL.

string

Optional brand name.

array

Optional UTM parameters as key/value pairs.

ad_text_mode is not accepted here. The router also rejects source, status, review_status, review_reason, metadata, and generate_static_text because those fields are server-managed.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/ad-units \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer headline variant",
    "headline": "Postgres for teams",
    "description": "Launch faster with managed Postgres.",
    "landing_page": "https://acme.com/summer",
    "static_ad_text": "Managed Postgres with built-in scaling.",
    "static_cta": "Start free",
    "brand_name": "Acme"
  }'

Response

{
  "id": "ad-123",
  "name": "Summer headline variant",
  "headline": "Postgres for teams",
  "description": "Launch faster with managed Postgres.",
  "landing_page": "https://acme.com/summer",
  "static_ad_text": "Managed Postgres with built-in scaling.",
  "static_cta": "Start free",
  "favicon_url": "https://acme.com/favicon.ico",
  "image_url": null,
  "brand_name": "Acme",
  "source": "manual",
  "status": "draft",
  "review_status": "not_submitted",
  "review_reason": null,
  "utm_params": [],
  "created_at": "2025-05-01T00:00:00",
  "updated_at": "2025-05-01T00:00:00",
  "campaign_id": null
}

POST `/advertiser-dashboard/campaigns/{campaign_id}/ad-units/generate`

Generate draft ad units from a landing page URL.

string

required

The campaign ID.

string

required

Landing page URL to scrape.

integer

Number of draft ad units to generate, from 1 to 5.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/campaigns/camp-456/ad-units/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://acme.com/summer",
    "count": 3
  }'

Response

{
  "campaign_id": "camp-456",
  "ad_units": [
    {
      "id": "ad-123",
      "name": "Managed Postgres for teams",
      "headline": "Postgres for teams",
      "description": "Launch faster with managed Postgres.",
      "landing_page": "https://acme.com/summer",
      "static_ad_text": "Managed Postgres with built-in scaling.",
      "static_cta": "Start free",
      "favicon_url": "https://acme.com/favicon.ico",
      "image_url": null,
      "brand_name": "Acme",
      "source": "scraped",
      "status": "draft",
      "review_status": "not_submitted",
      "review_reason": null,
      "utm_params": [],
      "created_at": "2025-05-01T00:00:00",
      "updated_at": "2025-05-01T00:00:00",
      "campaign_id": null
    }
  ]
}

POST `/advertiser-dashboard/campaigns/{campaign_id}/ad-units`

Add ad units to a campaign without replacing the existing set.

string

required

The campaign ID.

array

required

One or more ad-unit IDs. Duplicate IDs are deduped before write.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/campaigns/camp-456/ad-units \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_unit_ids": ["ad-123", "ad-456"]
  }'

Response

{
  "campaign_id": "camp-456",
  "ad_unit_ids": ["ad-123", "ad-456"]
}

The router marks linked units for review when needed, resubmits already-approved campaigns that now contain unreviewed ad units, and schedules the campaign ad-unit sync task in the background.

PUT `/advertiser-dashboard/campaigns/{campaign_id}/ad-units`

Replace the campaign’s ad-unit set.

string

required

The campaign ID.

array

required

Replacement ad-unit IDs. Duplicate IDs are deduped before write.

curl -X PUT https://platform.trygravity.ai/advertiser-dashboard/campaigns/camp-456/ad-units \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_unit_ids": ["ad-456", "ad-789"]
  }'

Response

{
  "campaign_id": "camp-456",
  "ad_unit_ids": ["ad-456", "ad-789"]
}

This route has the same ownership checks and review/sync behavior as the POST variant, but it replaces the existing linked set before returning.

PATCH `/advertiser-dashboard/ad-units/{ad_unit_id}/archive`

Toggle an ad unit’s archived state.

string

required

The ad unit ID.

curl -X PATCH https://platform.trygravity.ai/advertiser-dashboard/ad-units/ad-123/archive \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "ad_unit_id": "ad-123",
  "status": "archived"
}

Unarchiving restores status = "draft".

Managing pixels

POST `/advertiser-dashboard/pixels`

Create a conversion pixel for a site. Verification of the pixel installation runs in the background after creation.

string

required

The site URL the pixel will be installed on. https:// is prepended if no scheme is given.

string

Display name for the pixel. Defaults to Untitled Pixel.

curl -X POST https://platform.trygravity.ai/advertiser-dashboard/pixels \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.com",
    "name": "Acme main site"
  }'

Response (201)

{
  "pixel_id": "pix-123",
  "url": "https://acme.com",
  "name": "Acme main site",
  "is_active": true,
  "is_functional": null,
  "account_id": "acct-789",
  "created_at": "2026-07-01T12:00:00"
}

is_functional starts as null and flips to true/false once background verification confirms whether the pixel script is installed on the URL. Returns 409 if a pixel already exists for the URL, and 422 if the URL is invalid.

GET `/advertiser-dashboard/pixels`

List all pixels on your account.

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

Response

[
  {
    "pixel_id": "pix-123",
    "url": "https://acme.com",
    "name": "Acme main site",
    "is_active": true,
    "is_functional": true,
    "account_id": "acct-789",
    "created_at": "2026-07-01T12:00:00"
  }
]

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

An advertiser API key unlocks read-only tools mirroring this API: advertiser_get_info, advertiser_list_campaigns, advertiser_get_campaign, advertiser_get_metrics, advertiser_get_conversions, advertiser_get_billing, advertiser_get_events_analytics, advertiser_get_conversion_stats, and advertiser_get_integrations.

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/advertiser-dashboard"

# Get last 30 days of metrics
metrics = requests.get(
    f"{BASE}/metrics",
    headers={"X-API-Key": API_KEY},
    params={"days": 30},
).json()

print(f"Impressions: {metrics['total_impressions']:,}")
print(f"Spend: ${metrics['total_spend']:.2f}")
print(f"Conversions: {metrics['total_conversions']}")
print(f"ROAS: {metrics['total_revenue'] / metrics['total_spend']:.2f}x" if metrics['total_spend'] > 0 else "")

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

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

console.log(`Impressions: ${metrics.total_impressions.toLocaleString()}`);
console.log(`Spend: $${metrics.total_spend.toFixed(2)}`);
console.log(`Conversions: ${metrics.total_conversions}`);

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

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

# List active campaigns
curl "https://platform.trygravity.ai/advertiser-dashboard/campaigns?status=active" \
  -H "X-API-Key: YOUR_API_KEY"

Errors

Status	Description
`401`	Invalid or missing `X-API-Key`.
`400`	Invalid parameter (e.g. out-of-range `days`).
`402`	Campaign activation is blocked by billing.
`404`	Campaign not found or doesn’t belong to your account.
`422`	Validation errors, including missing/empty `ad_unit_ids`, removed fields like `keywords` and `ad_text_mode`, missing required ad-unit fields, invalid favicon URLs, invalid lead-form config, or no update fields on `PATCH /campaigns/{campaign_id}`.

Questions

Email support@trygravity.ai for anything API-related. We read it.

​Base URL

​Authentication

​Endpoints

​GET /advertiser-dashboard/info

​GET /advertiser-dashboard/campaigns

​GET /advertiser-dashboard/campaigns/{campaign_id}

​GET /advertiser-dashboard/metrics

​GET /advertiser-dashboard/ad-unit-metrics

​GET /advertiser-dashboard/conversions

​GET /advertiser-dashboard/billing

​GET /advertiser-dashboard/events/analytics

​GET /advertiser-dashboard/events/conversion-stats

​GET /advertiser-dashboard/integrations

​Managing campaigns

​POST /advertiser-dashboard/campaigns

​PATCH /advertiser-dashboard/campaigns/{campaign_id}

​PATCH /advertiser-dashboard/campaigns/{campaign_id}/archive

​Managing ad groups & ads

​GET /advertiser-dashboard/ad-groups

​POST /advertiser-dashboard/ad-groups

​GET /advertiser-dashboard/ad-groups/{ad_group_id}

​PATCH /advertiser-dashboard/ad-groups/{ad_group_id}

​DELETE /advertiser-dashboard/ad-groups/{ad_group_id}

​POST /advertiser-dashboard/ad-groups/{ad_group_id}/ads

​PATCH /advertiser-dashboard/ads/{ad_id}

​DELETE /advertiser-dashboard/ads/{ad_id}

​Legacy: ad units (deprecated)

​POST /advertiser-dashboard/ad-units

​POST /advertiser-dashboard/campaigns/{campaign_id}/ad-units/generate

​POST /advertiser-dashboard/campaigns/{campaign_id}/ad-units

​PUT /advertiser-dashboard/campaigns/{campaign_id}/ad-units

​PATCH /advertiser-dashboard/ad-units/{ad_unit_id}/archive

​Managing pixels

​POST /advertiser-dashboard/pixels

​GET /advertiser-dashboard/pixels

​MCP server

​Code examples

​Errors

​Questions

Base URL

Authentication

Endpoints

GET `/advertiser-dashboard/info`

GET `/advertiser-dashboard/campaigns`

GET `/advertiser-dashboard/campaigns/{campaign_id}`

GET `/advertiser-dashboard/metrics`

GET `/advertiser-dashboard/ad-unit-metrics`

GET `/advertiser-dashboard/conversions`

GET `/advertiser-dashboard/billing`

GET `/advertiser-dashboard/events/analytics`

GET `/advertiser-dashboard/events/conversion-stats`

GET `/advertiser-dashboard/integrations`

Managing campaigns

POST `/advertiser-dashboard/campaigns`

PATCH `/advertiser-dashboard/campaigns/{campaign_id}`

PATCH `/advertiser-dashboard/campaigns/{campaign_id}/archive`

Managing ad groups & ads

GET `/advertiser-dashboard/ad-groups`

POST `/advertiser-dashboard/ad-groups`

GET `/advertiser-dashboard/ad-groups/{ad_group_id}`

PATCH `/advertiser-dashboard/ad-groups/{ad_group_id}`

DELETE `/advertiser-dashboard/ad-groups/{ad_group_id}`

POST `/advertiser-dashboard/ad-groups/{ad_group_id}/ads`

PATCH `/advertiser-dashboard/ads/{ad_id}`

DELETE `/advertiser-dashboard/ads/{ad_id}`

Legacy: ad units (deprecated)

POST `/advertiser-dashboard/ad-units`

POST `/advertiser-dashboard/campaigns/{campaign_id}/ad-units/generate`

POST `/advertiser-dashboard/campaigns/{campaign_id}/ad-units`

PUT `/advertiser-dashboard/campaigns/{campaign_id}/ad-units`

PATCH `/advertiser-dashboard/ad-units/{ad_unit_id}/archive`

Managing pixels

POST `/advertiser-dashboard/pixels`

GET `/advertiser-dashboard/pixels`

MCP server

Code examples

Errors

Questions