# GET /v1/stats

Get statistics

Pops, revenue and eCPM for the publisher, grouped by date, hour, site, zone, country, device, os, browser or page_domain; JSON or CSV. The browser filter accepts canonical browser keys. Revenue by browser is allocated in proportion to impressions. The browser view may be unavailable or switched off; check /v1/stats/availability. Unavailable browser grouping or filtering returns 400 breakdown_unavailable with breakdown browser (JSON and CSV) before statistics queries. Grouping or filtering by page_domain is available only once measurement is active: before that it returns 400 `page_domain_unavailable`, and JSON responses carry `page_domain_available`. With group_by containing `hour` the range (both ends inclusive, EST business days) must be at most 31 days, otherwise 400 `hour_range`; hourly revenue of finalized days is an allocation of the daily revenue (response has `hourly_revenue_allocated: true`), not a per-hour measurement; hours of days not yet finalized are estimates. JSON hours are ISO UTC; CSV hours display EST (UTC-5). Each row has status estimated, reported, final or mixed; zero valid impressions have null eCPM. The response identifies the accepted count and money snapshot. Requires scope publisher:read (API key or web session). Rate limit tier: stats.

- Required scope: `publisher:read`
- Rate limit: `stats` — 30 requests per 60-second window per API key or web session

## Parameters

| Name | In | Type | Required |
|---|---|---|---|
| `from` | query | string | yes |
| `to` | query | string | yes |
| `group_by` | query | ("date" \| "hour" \| "site" \| "zone" \| "country" \| "device" \| "os" \| "browser" \| "page_domain")[] | no |
| `metrics` | query | ("pops" \| "revenue" \| "ecpm")[] | no |
| `site_id` | query | integer | no |
| `zone_id` | query | integer | no |
| `country` | query | string | no |
| `browser` | query | "chrome" \| "safari" \| "firefox" \| "edge" \| "samsung_internet" \| "opera" \| "uc_browser" \| "yandex" \| "other" | no |
| `page_domain` | query | string | no |
| `format` | query | "json" \| "csv" | no |

## Response

```
{ browser_missing_days?: string[]; count_basis?: "valid" | "legacy" | "mixed"; currency: "USD"; data_as_of?: string | null; estimated_from: string | null; forecast_basis_version?: "forecast-basis-v1"; forecast_generation?: string; forecast_updated_at?: string | null; hourly_revenue_allocated?: true; measurement_definition?: { complete: boolean; includes_direct: boolean; includes_legacy: boolean; tag_valid_after_ms: integer[] }; measurement_generation?: string; measurement_status?: "ok" | "stale" | "updating"; measurement_updated_at?: string | null; money_basis_version?: string; money_generation?: string; page_domain_available?: boolean; rows: { browser?: "chrome" | "safari" | "firefox" | "edge" | "samsung_internet" | "opera" | "uc_browser" | "yandex" | "other"; country?: string; date?: string; device?: string; ecpm?: string | null; hour?: string; os?: string; page_domain?: string | null; pops?: integer; publisher_id?: integer; revenue?: string; site_deleted?: true; site_domain?: string; site_id?: integer; status?: "estimated" | "reported" | "final" | "mixed"; zone_deleted?: true; zone_id?: integer; zone_name?: string }[]; totals: { ecpm: string | null; pops: integer; revenue: string; status?: "estimated" | "reported" | "final" | "mixed" }; truncated?: boolean; updated_at?: string | null }
```

## Errors

Rate-limited routes return `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window ends); a 429 also carries `Retry-After`. The headers may be absent while the limiter is temporarily unavailable (requests are then let through).

| Status | Meaning |
|---|---|
| 401 | Missing, invalid or revoked API key. |
| 403 | The key lacks the required scope, or the operation is not allowed for this actor. |
| 429 | Rate limit exceeded; wait `Retry-After` seconds. |
| 400 | Default Response |
| 404 | Default Response |
| 503 | Default Response |

## Examples

### cURL

```bash
#!/usr/bin/env bash
# GET /v1/stats: daily pops, revenue and eCPM for the last 7 calendar days (EST, fixed UTC-5).
# Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE, AGIMONE_FROM, AGIMONE_TO.
set -euo pipefail
BASE="${AGIMONE_API_BASE:-https://app.agimone.com}"
# Snapshot the EST day once; calendar arithmetic uses that date label.
TODAY="$(TZ=Etc/GMT+5 date +%F)"
# `date -v` is BSD/macOS, `date -d` is GNU/Linux.
FROM="${AGIMONE_FROM:-$(date -u -j -v-6d -f '%Y-%m-%d' "$TODAY" +%F 2>/dev/null || date -u -d "$TODAY -6 days" +%F)}"
TO="${AGIMONE_TO:-$TODAY}"
curl -fsS -H "Authorization: Bearer $AGIMONE_API_KEY" \
  "$BASE/v1/stats?from=$FROM&to=$TO&group_by=date&metrics=pops,revenue,ecpm"
echo
```

### Node.js

```js
// GET /v1/stats: daily pops, revenue and eCPM for the last 7 calendar days (EST, fixed UTC-5). Node 18+, no dependencies.
// Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE, AGIMONE_FROM, AGIMONE_TO.
const base = process.env.AGIMONE_API_BASE ?? 'https://app.agimone.com';
const parts = new Intl.DateTimeFormat('en-US', { timeZone: 'Etc/GMT+5', year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(new Date());
const part = (type) => parts.find((p) => p.type === type).value;
const today = `${part('year')}-${part('month')}-${part('day')}`;
const day = (offset) => new Date(Date.parse(`${today}T00:00:00Z`) + offset * 86_400_000).toISOString().slice(0, 10);
const query = new URLSearchParams({
  from: process.env.AGIMONE_FROM ?? day(-6),
  to: process.env.AGIMONE_TO ?? today,
  group_by: 'date',
  metrics: 'pops,revenue,ecpm',
});

const res = await fetch(`${base}/v1/stats?${query}`, {
  headers: { Authorization: `Bearer ${process.env.AGIMONE_API_KEY}` },
});
if (!res.ok) {
  console.error(`HTTP ${res.status}: ${await res.text()}`);
  process.exit(1);
}
console.log(JSON.stringify(await res.json()));
```

### PHP

```php
<?php
// GET /v1/stats: daily pops, revenue and eCPM for the last 7 calendar days (EST, fixed UTC-5). PHP 8 with the curl extension, no other dependencies.
// Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE, AGIMONE_FROM, AGIMONE_TO.
$base = getenv('AGIMONE_API_BASE') ?: 'https://app.agimone.com';
$today = new DateTimeImmutable('now', new DateTimeZone('Etc/GMT+5'));
$query = http_build_query([
    'from' => getenv('AGIMONE_FROM') ?: $today->modify('-6 days')->format('Y-m-d'),
    'to' => getenv('AGIMONE_TO') ?: $today->format('Y-m-d'),
    'group_by' => 'date',
    'metrics' => 'pops,revenue,ecpm',
]);

$ch = curl_init("$base/v1/stats?$query");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AGIMONE_API_KEY')],
    CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
    fwrite(STDERR, "HTTP $status: " . ($body === false ? curl_error($ch) : $body) . "\n");
    exit(1);
}
curl_close($ch);
echo trim($body), "\n";
```

### Python

```python
# GET /v1/stats: daily pops, revenue and eCPM for the last 7 calendar days (EST, fixed UTC-5). Python 3.8+, standard library only.
# Needs: AGIMONE_API_KEY (create one at https://app.agimone.com/app/account/api-keys). Optional: AGIMONE_API_BASE, AGIMONE_FROM, AGIMONE_TO.
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request
from datetime import datetime, timedelta, timezone

base = os.environ.get("AGIMONE_API_BASE", "https://app.agimone.com")
# Fixed UTC-5 is Etc/GMT+5; Python 3.8 needs no zoneinfo/tzdata dependency.
today = datetime.now(timezone(timedelta(hours=-5))).date()
query = urllib.parse.urlencode({
    "from": os.environ.get("AGIMONE_FROM", str(today - timedelta(days=6))),
    "to": os.environ.get("AGIMONE_TO", str(today)),
    "group_by": "date",
    "metrics": "pops,revenue,ecpm",
})
req = urllib.request.Request(
    f"{base}/v1/stats?{query}",
    headers={"Authorization": f"Bearer {os.environ['AGIMONE_API_KEY']}"},
)
try:
    with urllib.request.urlopen(req, timeout=15) as res:
        print(json.dumps(json.load(res)))
except urllib.error.HTTPError as e:
    print(f"HTTP {e.code}: {e.read().decode()}", file=sys.stderr)
    sys.exit(1)
```

HTML documentation: https://agimone.com/en/developers/api/#get-stats
API 2026-10
