> ## 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.

# Revenue insights and agreement statements

> See where your revenue per user comes from, and read the monthly statement of a qualifying-request agreement.

Use these endpoints to see where your revenue per user comes from, and, if you have a qualifying-request agreement, to read its monthly statement.

## Revenue per user

### GET `/publisher-dashboard/user-analytics`

See where your revenue per user comes from: by day, new and returning users, usage, ad load, country, signup week, and your own user tags. Every publisher can call this route.

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

The number of days to look back, from 1 to 365. Or send `start_date` and `end_date` (`YYYY-MM-DD`).

**country** `string`

Comma-separated ISO country codes, or `unknown`. At most 20 countries.

**segment** `string`

Comma-separated: `new`, `returning`.

**usage** `string`

Comma-separated usage groups: `under_10`, `10_24`, `25_49`, `50_99`, `100_plus` (requests per active day).

Gravity ignores filter values that it doesn't know.

| Field | Description |
| - | - |
| `start_date` / `end_date` / `period_days` | The range of the report. |
| `data_since` | The first day that Gravity has user data for your account. |
| `summary` | `active_users`, `new_users`, `returning_users`, `arpu`, `arpdau` (payout per active user day), `payout`, and `attributed_impression_share` (the share of impressions that Gravity could attribute to a user). |
| `daily` | One row per day: `day`, `active_users`, `new_users`, `impressions`, `arpu`. |
| `new_vs_returning` / `by_usage` / `by_ad_load` / `by_country` | Segment rows. Ad load groups are `none`, `under_5`, `5_9`, `10_19`, and `20_plus` impressions per active day. `by_country` has up to 25 countries. |
| `concentration` | The revenue share of the top 1%, 5%, and 20% of users: `top_pct`, `users`, `revenue_share`. |
| `signup_cohorts` | One row per signup week: `week`, `users`, `d7_retention`, `first_week_arpu`. The last two are `null` until every user in the week has had 7 full days. |
| `tags` | ARPU for each value of your `user.tags` keys, up to 20 values per key: `key` and `values` (segment rows). |
| `trends` | Daily ARPU for new and returning users and for the top countries: `section`, `segment`, and `points` (`day`, `users`, `arpu`). |

Each segment row has `segment`, `users`, `user_days`, `impressions`, `clicks`, `ctr`, `arpu`, `arpdau`, and `revenue_share`.

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

## Agreement statements

These routes return the monthly statement of a qualifying-request agreement. They exist only for publishers on that kind of agreement. For any other key, they return `404`.

Both take `month` (any date in the month, `YYYY-MM-DD`; the default is the current month) and `tz` (an IANA time zone, default `UTC`). A bad `month` or `tz` returns `400`. A future month returns `404`. Amounts that end in `_microdollars` are in millionths of a dollar.

### GET `/publisher-dashboard/qualifying-requests`

Get the qualifying requests, rate, tier, and earnings of one month.

`accrued_minimum_microdollars` is the minimum for the days of the month that the agreement covers, not a full month. `earned_month_to_date` and `earned_today` are in dollars.

```json Response theme={null}
{
  "publisher_id": "abc-123",
  "month": "2026-10",
  "qualifying_requests": 1250000,
  "rate_microdollars": 400,
  "tier": 1,
  "monthly_cap_microdollars": null,
  "accrued_minimum_microdollars": null,
  "daily_cap_microdollars": null,
  "earned_month_to_date": 500.0,
  "earned_today": 18.4,
  "qualifying_requests_today": 46000,
  "month_closed": false,
  "as_of": "2026-10-28"
}
```

### GET `/publisher-dashboard/proven-ad-value`

Get the Publisher Attributable Value (PAV) of one month, by conversion event. Gravity uses the same calculation for the monthly reconciliation. This route is available only when your agreement shows PAV to you.

`types` always lists every conversion event of the agreement's rate card, in the agreement's order, including events with a zero value. `provisional` is `true` until the month is over, because conversions can still arrive.

```json Response theme={null}
{
  "publisher_id": "abc-123",
  "month": "2026-10",
  "pav_microdollars": 1200000000,
  "tier": 1,
  "monthly_cap_microdollars": 5000000000,
  "provisional": true,
  "rate_card_version": "v1",
  "brand_spend_microdollars": 300000000,
  "types": [
    { "type": "Purchase", "value_microdollars": 800000000 },
    { "type": "SaaS signup", "value_microdollars": 0 }
  ]
}
```


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