> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports and account data

> Read your profile, campaigns, metrics, conversions, billing, pixel events, and integrations.

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.

**X-API-Key** `string` *required*

Your advertiser API key.

```bash Request theme={null}
curl https://platform.trygravity.com/advertiser-dashboard/info \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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).

**status** `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`. |

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/campaigns" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

**campaign\_id** `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`.

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/campaigns/camp-456" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

**days** `integer` (default: 30)

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

**start\_date** `string`

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

**end\_date** `string`

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

**campaign\_id** `string`

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

**tz** `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`.

> [!NOTE]
>
> 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. |

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/metrics?days=7&tz=America/New_York" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

> [!NOTE]
>
> 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`.

**days** `integer` (default: 30)

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

**start\_date** `string`

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

**end\_date** `string`

The last day (`YYYY-MM-DD`).

**campaign\_id** `string`

Show only one campaign.

**ad\_unit\_id** `string`

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

**tz** `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). |

```bash Request theme={null}
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"
```

```json Response theme={null}
{
  "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.

> [!NOTE]
>
> 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.

**days** `integer` (default: 30)

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

**start\_date** `string`

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

**end\_date** `string`

The last day (`YYYY-MM-DD`).

**campaign\_id** `string`

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

**ad\_group\_id** `string`

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

**include\_archived** `boolean` (default: false)

Include archived ad groups.

**offset** `integer` (default: 0)

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

**tz** `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. |

```bash Request theme={null}
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"
```

```json Response theme={null}
{
  "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.

**limit** `integer` (default: 50)

The page size, from 1 to 100.

**cursor** `string`

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

**campaign\_id** `string`

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

**event\_type** `string`

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

**attribution\_type** `string`

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

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/conversions?limit=10" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/billing" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

**days** `integer` (default: 30)

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

**start\_date** `string`

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

**end\_date** `string`

The last day (`YYYY-MM-DD`).

**domain** `string`

Show only the domains that contain this text.

**event\_type** `string`

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

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/events/analytics?days=30" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

**days** `integer` (default: 30)

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

**start\_date** `string`

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

**end\_date** `string`

The last day (`YYYY-MM-DD`).

**event\_type** `string`

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

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/events/conversion-stats?days=30" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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](https://docs.trygravity.com/advertisers/integrations.md).

```bash Request theme={null}
curl "https://platform.trygravity.com/advertiser-dashboard/integrations" \
  -H "X-API-Key: YOUR_API_KEY"
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.