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

> Read your profile, earnings, request funnel, and results by device and country.

Use these read-only endpoints to get the numbers from your publisher dashboard: your profile, daily earnings, the ad request funnel, and results by device and country.

## GET `/publisher-dashboard/info`

Returns your publisher profile and lifetime totals.

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

Your Gravity API key.

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

```json Response theme={null}
{
  "publisher_id": "abc-123",
  "name": "My Platform",
  "url": "https://myplatform.com",
  "payout_model": "CPM",
  "total_impressions": 7800000,
  "total_clicks": 42000
}
```

## GET `/publisher-dashboard/stats`

Returns a daily time series of impressions, clicks, revenue, CPM, CPC, and CTR. The values are the same as on the **Overview** and **Earnings** pages of the dashboard.

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

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

**start\_date** `string`

The start date (`YYYY-MM-DD`). Use it with `end_date`. A date range replaces `days`.

**end\_date** `string`

The end date (`YYYY-MM-DD`).

**tz** `string` (default: UTC)

The IANA time zone for the daily buckets, for example `America/New_York`.

The response has more fields than the example. The example shows the main fields.

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

```json Response theme={null}
{
  "totalImpressions": 250000,
  "totalClicks": 1200,
  "totalRevenue": 1250.50,
  "avgCpm": 5.00,
  "avgCpc": 1.04,
  "avgCtr": 0.48,
  "timeSeries": [
    {
      "date": "2025-05-20",
      "impressions": 35000,
      "clicks": 170,
      "revenue": 178.50,
      "cpm": 5.10,
      "cpc": 1.05,
      "ctr": 0.49
    }
  ]
}
```

## GET `/publisher-dashboard/activity`

Returns the ad request funnel: requests, wins, impressions, fill rate, and show rate.

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

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

**start\_date** `string`

The start date (`YYYY-MM-DD`). Use it with `end_date`. A date range replaces `days`.

**end\_date** `string`

The end date (`YYYY-MM-DD`).

**tz** `string` (default: UTC)

The IANA time zone for the daily buckets, for example `America/New_York`.

| Field | Description |
| - | - |
| `fill_rate` | How often a campaign matched: `wins / requests`. |
| `show_rate` | How often a matched ad became visible: `impressions / wins`. |
| `bot_requests`, `total_bot_requests`, `bot_request_rate` | The requests that the engine marked as bot traffic. |

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

```json Response theme={null}
{
  "data": [
    {
      "date": "2025-05-20",
      "requests": 50000,
      "bot_requests": 500,
      "wins": 35000,
      "impressions": 30000
    }
  ],
  "total_requests": 350000,
  "total_bot_requests": 3500,
  "bot_request_rate": 0.01,
  "total_wins": 245000,
  "total_impressions": 210000,
  "fill_rate": 0.70,
  "show_rate": 0.8571
}
```

## GET `/publisher-dashboard/devices`

Returns the results for each device type (desktop, mobile, and tablet).

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

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

**start\_date** `string`

The start date (`YYYY-MM-DD`). Use it with `end_date`. A date range replaces `days`.

**end\_date** `string`

The end date (`YYYY-MM-DD`).

**tz** `string` (default: UTC)

The IANA time zone for the daily buckets, for example `America/New_York`.

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

```json Response theme={null}
{
  "devices": [
    {
      "device_type": "desktop",
      "impressions": 150000,
      "clicks": 750,
      "ctr": 0.005,
      "revenue": 750.00,
      "cpm": 5.00,
      "cpc": 1.00,
      "daily": [
        {
          "date": "2025-05-20",
          "device_type": "desktop",
          "impressions": 5000,
          "clicks": 25,
          "ctr": 0.005,
          "revenue": 25.00,
          "cpm": 5.00,
          "cpc": 1.00
        }
      ]
    }
  ],
  "period_days": 30
}
```

## GET `/publisher-dashboard/geography`

Returns the results for each country.

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

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

**start\_date** `string`

The start date (`YYYY-MM-DD`). Use it with `end_date`. A date range replaces `days`.

**end\_date** `string`

The end date (`YYYY-MM-DD`).

**tz** `string` (default: UTC)

The IANA time zone for the daily buckets, for example `America/New_York`.

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

```json Response theme={null}
{
  "countries": [
    {
      "country_code": "US",
      "impressions": 500000,
      "clicks": 2500,
      "ctr": 0.005,
      "revenue": 2500.00,
      "cpm": 5.00,
      "cpc": 1.00
    }
  ],
  "period_days": 30
}
```

## GET `/publisher-dashboard/countries`

Returns your top countries by number of requests, with the number of unique users in each country.

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

The number of countries to return, from 1 to 100.

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

```json Response theme={null}
{
  "countries": [
    {
      "country_code": "US",
      "requests": 200000,
      "ads_served": 140000,
      "unique_users": 8000,
      "pct_requests": 57.1
    }
  ]
}
```


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