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

# Users and segments

> Rank your users by usage and value, and attach email identities.

These routes show how your users differ in usage and value, and where one user ranks. Gravity builds them from the `pub_user_id` values that you send on ad requests.

> [!NOTE]
>
> These routes are available only when Gravity turns on the user value API for your publisher account. Otherwise they return `404`.

The date parameters work the same on each route: `days` (1 to 365, default 30), or `start_date` and `end_date` (`YYYY-MM-DD`). A range longer than 365 days returns `400`.

`arpu` is on a payout basis. Gravity splits the payout of the range (what `/stats` reports) across users by their share of attributed revenue. These routes return ranks, shares, and averages, not revenue totals.

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

Compare groups of the users who were active in the range.

**country\_limit** `integer` (default: 20)

The number of countries in `by_country`, from 1 to 100.

| Field | Description |
| - | - |
| `usage_segments` | Users ranked by ad requests, in cumulative groups: `top_10_pct`, `top_20_pct`, `top_30_pct`, `top_40_pct`, and `all`. |
| `value_segments` | Users ranked by revenue per user: `top_10_pct_by_arpu`, `bottom_10_pct_by_arpu`, and `all`. |
| `usage_deciles` / `value_deciles` | The same two rankings in separate 10% groups (`0_10_pct` to `90_100_pct`). Empty when fewer than 10 users were active. |
| `by_country` | The number of active users in each country. `Unknown` when the country isn't known. |
| `ctr` | Clicks / impressions, as a fraction. |
| `revenue_share` | The group's share (0 to 1) of the revenue attributed to active users. |

The activity counters are lifetime totals for each user. The range selects which users are included.

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

```json Response theme={null}
{
  "usage_segments": [
    {
      "segment": "top_10_pct",
      "users": 120,
      "requests": 48000,
      "ads_served": 30000,
      "impressions": 26000,
      "clicks": 310,
      "ctr": 0.0119,
      "arpu": 1.42,
      "revenue_share": 0.38
    }
  ],
  "value_segments": [],
  "usage_deciles": [],
  "value_deciles": [],
  "by_country": [{ "country_code": "US", "users": 640 }],
  "total_users": 1200,
  "period_days": 30
}
```

## GET `/publisher-dashboard/users/{pub_user_id}/segment`

Find the groups that one user belongs to, ranked against the same users as `/user-segments`. The response has ranks and groups only, no revenue.

**pub\_user\_id** `string` *required*

Your ID for the user. With `id_type=email`, send the email address or its SHA-256 hash.

**id\_type** `string` (default: pub\_user\_id)

`pub_user_id` or `email`. An email lookup works only for users whose email you sent with `/users/identify` or who submitted a lead form.

`usage_bucket` is `top_10_pct` to `top_40_pct`, or `below_top_40_pct`. `value_bucket` is `top_10_pct_by_arpu`, `bottom_10_pct_by_arpu`, or `middle`. A percentile is the share of users ranked above this user (`0.0` is the first user). If the user doesn't exist or wasn't active in the range, the response is `404`.

```json Response theme={null}
{
  "pub_user_id": "user-123",
  "usage_decile": 1,
  "usage_percentile": 0.04,
  "usage_bucket": "top_10_pct",
  "value_decile": 3,
  "value_percentile": 0.27,
  "value_bucket": "middle",
  "total_users": 1200,
  "period_days": 30
}
```

## POST `/publisher-dashboard/users/identify`

Attach email identities to your users, so you can look them up by email. Gravity attaches an identity only to a user it has already seen.

**users** `array` *required*

From 1 to 1,000 items. Each item has `pub_user_id` and one of `email` or `hashed_email`. Gravity hashes `email` and doesn't store it. `hashed_email` is the SHA-256 hex digest (64 characters) of the lowercased, trimmed address.

A blank `pub_user_id`, an `email` with no `@`, a `hashed_email` that isn't 64 hex characters, or an item with neither field returns `422`.

```bash Request theme={null}
curl -X POST https://platform.trygravity.com/publisher-dashboard/users/identify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users": [{"pub_user_id": "user-123", "email": "jane@example.com"}]}'
```

```json Response theme={null}
{
  "received": 1,
  "matched": 1,
  "unmatched_pub_user_ids": []
}
```

## GET `/publisher-dashboard/arpu-trend`

Get the number of active users on each UTC day, and the users who first appeared in the range, grouped by week. `cohort_week` is the Monday that starts the week.

```json Response theme={null}
{
  "daily": [{ "date": "2026-10-20", "active_users": 410 }],
  "cohorts": [{ "cohort_week": "2026-10-19", "users": 95 }],
  "period_days": 30
}
```


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