Skip to main content
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.
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.
​
integer
default:"20"
The number of countries in by_country, from 1 to 100.
The activity counters are lifetime totals for each user. The range selects which users are included.
Request
Response

​
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.
​
string
required
Your ID for the user. With id_type=email, send the email address or its SHA-256 hash.
​
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.
Response

​
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.
​
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.
Request
Response

​
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.
Response