Reports and account data

Use these read-only endpoints to pull your advertiser data: your profile, campaigns with their statistics, daily metrics at the campaign, ad group, and ad unit level, conversions, billing, pixel events, and connected stores.

GET `/advertiser-dashboard/info`

Get your advertiser profile.

string

required

Your advertiser API key.

Request

curl https://platform.trygravity.com/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 your campaigns with their lifetime statistics (impressions, clicks, spend, and conversions).

string

Show only the campaigns with this status: active, paused, or draft.

Field	Description
`status`	The status that you set: `active`, `paused`, or `draft`.
`delivery_status`	Tells if the campaign can serve now: `draft`, `scheduled`, `pending_review`, `eligible`, `limited`, `not_eligible`, `paused`, or `ended`.
`delivery_issues`	The reasons when delivery is limited or blocked, for example `all_ads_rejected` or `ad_image_required`.

Request

curl "https://platform.trygravity.com/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,
      "budget_type": "daily",
      "landing_page": "https://acme.com/summer",
      "campaign_objective": "conversions",
      "billing_model": "cpm",
      "created_at": "2025-05-01T00:00:00",
      "start_time": "2025-05-01T00:00:00",
      "end_time": null,
      "delivery_status": "eligible",
      "delivery_issues": [],
      "impressions": 350000,
      "clicks": 1800,
      "spend": 875.50,
      "conversions": 42,
      "click_through_conversions": 40,
      "view_through_conversions": 2,
      "conversion_value": 4200.00
    }
  ]
}

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

Get one campaign with its full statistics and its target settings.

string

required

The campaign ID.

The response also has all the fields of the list response. If the campaign is not in your account, the response is 404.

Request

curl "https://platform.trygravity.com/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": ["web", "ios_app"],
  "utm_params": [{ "key": "utm_source", "value": "gravity" }],
  "deployment_status": "deployed",
  "impressions": 350000,
  "clicks": 1800,
  "spend": 875.50,
  "conversions": 42,
  "conversion_value": 4200.00
}

GET `/advertiser-dashboard/metrics`

Get daily performance metrics.

integer

default:"30"

The number of days to look back, from 1 to 365.

string

The first day (YYYY-MM-DD). If you send only start_date, the range ends today.

string

The last day (YYYY-MM-DD). If you send only end_date, the range starts days before it.

string

Show only one campaign. Omit it to get the totals for all campaigns.

string

default:"UTC"

The IANA time zone (for example America/New_York) that sets the start and end of each day. Set it to the time zone that your ad account uses for reports. Then the daily rows agree with the Gravity dashboard. For ChatGPT and OpenAI campaigns, they also agree with the OpenAI reports. OpenAI ad accounts currently report in America/New_York.

The tz parameter sets the days, not the time zone of the machine that calls the API. A day in UTC and the same day in America/New_York cover different hours, so the totals are different. Choose one time zone and always use it.

If start_date or end_date is not a valid date, or tz is not a valid time zone, the response is 400.

Metric	Description
`ctr`	The click-through rate (clicks / impressions × 100).
`cpc`	The cost per click (spend / clicks).
`cpm`	The cost per thousand impressions (spend / impressions × 1000).
`conversion_rate`	Conversions / clicks × 100.
`cpa`	The cost per acquisition (spend / conversions).
`roas`	The return on ad spend (revenue / spend).
`click_through_conversions` / `view_through_conversions`	The conversions after a click, and the conversions after a view with no click.

Request

curl "https://platform.trygravity.com/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,
      "click_through_conversions": 6,
      "view_through_conversions": 0,
      "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_click_through_conversions": 40,
  "total_view_through_conversions": 2,
  "total_revenue": 4200.00
}

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

Get daily metrics for each ad unit. These are the numbers in Ad units on the detail page of a campaign. Use this endpoint for reports at the creative level.The response has one series for each link between a campaign and an ad unit. Each series has a data_source:

ad_unit_stats: the series comes from real statistics for the ad unit.
campaign_fallback: the campaign has one linked ad unit and no ad unit rows yet. The series uses the daily totals of the campaign, so the numbers agree with the dashboard.

This endpoint gives impressions, clicks, spend, CTR, CPC, and CPM for each ad unit. Gravity attributes conversions, CPA, and ROAS at the campaign level. For those metrics, use /metrics or /conversions.

integer

default:"30"

The number of days to look back, from 1 to 365.

string

The first day (YYYY-MM-DD). The rules are the same as for /metrics.

string

The last day (YYYY-MM-DD).

string

Show only one campaign.

string

Show only one ad unit. If the ad unit is not in your account, the response is 404.

string

default:"UTC"

The IANA time zone (for example America/New_York) that sets the days. It works the same as on /metrics.

Field	Description
`data_source`	`ad_unit_stats` for real ad unit rows. `campaign_fallback` when a campaign with one ad unit uses the daily totals of the campaign.
`total_impressions` / `total_clicks` / `total_spend`	The totals of the series for the range.
`data[].ctr`	The click-through rate (clicks / impressions × 100).
`data[].cpc`	The cost per click (spend / clicks).
`data[].cpm`	The cost per thousand impressions (spend / impressions × 1000).

Request

curl "https://platform.trygravity.com/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
        }
      ]
    }
  ]
}

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

Get daily metrics for each ad group. A campaign contains ad groups, and an ad group contains ads. Use this endpoint for ad group reports, for example a weekly CSV.The response has one series for each ad group, with the sum for all publishers.

An ad group with no delivery in the range is in the list. It has zero totals and an empty data array.
A day with conversions but no delivery is in the list, with zero impressions.
One call returns at most 2,000 ad groups. Use total_ad_groups, truncated, and offset to get all of them.

Gravity counts conversions here the same way as campaign /metrics. It removes duplicates and applies the same attribution window. Currently, a conversion counts when it occurs within 7 days of a Gravity click or a Gravity view. This window can change. Gravity gives each conversion to the ad group that served the click. So the ad groups of a campaign never have more conversions than the campaign.Some conversions have no ad group: conversions from clicks before Gravity added ad group attribution, and view-through conversions. These show only in campaign /metrics. So the ad group conversions and Results of a campaign can be less than the campaign total. Use /metrics for the full count. Results count the conversion event that the campaign selected, the same way as Ads Manager.

integer

default:"30"

The number of days to look back, from 1 to 365.

string

The first day (YYYY-MM-DD). The rules are the same as for /metrics.

string

The last day (YYYY-MM-DD).

string

Show only one campaign. If the campaign is not in your account, the response is 404.

string

Show only one ad group. If the ad group is not in your account, the response is 404.

boolean

default:"false"

Include archived ad groups.

integer

default:"0"

The number of ad groups to skip. While truncated is true, send the request again with offset increased by 2000.

string

default:"UTC"

The IANA time zone (for example America/New_York) that sets the days. It works the same as on /metrics.

Field	Description
`total_ad_groups`	The number of ad groups that match your filters. This number ignores the limit of 2,000 for each call.
`truncated`	`true` when more ad groups match than the response contains. Send the request again with a higher `offset`.
`group_type`	`generative` or `manual`.
`total_impressions` / `total_clicks` / `total_spend` / `total_conversions` / `total_results` / `total_revenue` / `total_result_revenue`	The totals of the series for the range.
`result_type` / `result_label`	The result event that the campaign selected, for example `purchase` / `Purchase`. The value is `null` when the campaign objective has no Results.
`cpa`	The cost per acquisition (spend / conversions). The value is `null` when the group has no conversions.
`cost_per_result`	Spend / Results. The value is `null` when there are no Results.
`conversion_rate`	Results / clicks × 100. The value is `null` when there are no clicks.
`data[].conversions`	The conversions that Gravity attributed to this ad group on that day, in your `tz`.
`data[].click_through_conversions` / `data[].view_through_conversions`	The conversions of that day, divided into click-through and view-through.
`data[].results`	The conversions that match the result event of the campaign.
`data[].revenue` / `data[].result_revenue`	The conversion value in USD for all conversions, and for Results only. The value is `null` when no conversion has a USD value.
`data[].ctr`	The click-through rate (clicks / impressions × 100).
`data[].cpc`	The cost per click (spend / clicks).
`data[].cpm`	The cost per thousand impressions (spend / impressions × 1000).
`data[].cpa` / `data[].cost_per_result` / `data[].conversion_rate`	The same as the totals above, for that day.

Request

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

Response

{
  "ad_groups": [
    {
      "ad_group_id": "adg-789",
      "campaign_id": "camp-456",
      "name": "Summer Sale (Generative)",
      "group_type": "generative",
      "status": "active",
      "total_impressions": 1500,
      "total_clicks": 25,
      "total_spend": 7.50,
      "total_conversions": 4,
      "total_click_through_conversions": 4,
      "total_view_through_conversions": 0,
      "result_type": "purchase",
      "result_label": "Purchase",
      "total_results": 2,
      "total_revenue": 120.00,
      "total_result_revenue": 120.00,
      "cpa": 1.88,
      "cost_per_result": 3.75,
      "conversion_rate": 8.00,
      "data": [
        {
          "date": "2025-05-20",
          "impressions": 1000,
          "clicks": 20,
          "spend": 5.00,
          "conversions": 3,
          "click_through_conversions": 3,
          "view_through_conversions": 0,
          "results": 2,
          "revenue": 120.00,
          "result_revenue": 120.00,
          "ctr": 2.00,
          "cpc": 0.25,
          "cpm": 5.00,
          "cpa": 1.67,
          "cost_per_result": 2.50,
          "conversion_rate": 10.00
        }
      ]
    }
  ],
  "total_ad_groups": 1,
  "offset": 0,
  "truncated": false
}

GET `/advertiser-dashboard/conversions`

List your recent conversions, one page at a time. The list includes conversions with and without attribution.

integer

default:"50"

The page size, from 1 to 100.

string

The pagination cursor. Send the next_cursor value from the previous response.

string

Show only one campaign. If the campaign is not in your account, the response is 404.

string

Show only one conversion event type, for example purchase or lead.

string

Show only click_through or view_through conversions. When you set this filter, the response does not include conversions without attribution.

Request

curl "https://platform.trygravity.com/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,
      "attribution_type": "click_through"
    }
  ],
  "total_conversions": 42,
  "total_click_through_conversions": 40,
  "total_view_through_conversions": 2,
  "has_more": true,
  "next_cursor": "conv-788"
}

GET `/advertiser-dashboard/billing`

Get a billing summary: total spend, billed amount, unbilled amount, and credits.

Request

curl "https://platform.trygravity.com/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-15T00:00:00"
}

GET `/advertiser-dashboard/events/analytics`

Get the event analytics of your pixel: event counts for each domain, a time series, and counts for each event type.

integer

default:"30"

The number of days to look back, from 1 to 365.

string

The first day (YYYY-MM-DD). The rules are the same as for /metrics.

string

The last day (YYYY-MM-DD).

string

Show only the domains that contain this text.

string

Show only one event type, for example page_view, form_submit, or click.

Request

curl "https://platform.trygravity.com/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`

Get a conversion time series: the daily totals and the totals for each event type.

integer

default:"30"

The number of days to look back, from 1 to 365.

string

The first day (YYYY-MM-DD). The rules are the same as for /metrics.

string

The last day (YYYY-MM-DD).

string

Show only one conversion event type, for example purchase or lead.

Request

curl "https://platform.trygravity.com/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`

List your active Shopify store connections. To connect a store, see Integrations.

Request

curl "https://platform.trygravity.com/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"
    }
  ]
}

Get started

Advertisers

Publishers

API reference

Resources

Reports and account data

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/ad-group-metrics`

GET `/advertiser-dashboard/conversions`

GET `/advertiser-dashboard/billing`

GET `/advertiser-dashboard/events/analytics`

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

GET `/advertiser-dashboard/integrations`

​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/ad-group-metrics

​GET /advertiser-dashboard/conversions

​GET /advertiser-dashboard/billing

​GET /advertiser-dashboard/events/analytics

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

​GET /advertiser-dashboard/integrations

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/ad-group-metrics`

GET `/advertiser-dashboard/conversions`

GET `/advertiser-dashboard/billing`

GET `/advertiser-dashboard/events/analytics`

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

GET `/advertiser-dashboard/integrations`