# GET /v1/stats

Obtenir les statistiques

Pops, revenus et eCPM de l'éditeur, regroupés par date, hour, site, zone, country, device, os, browser ou page_domain ; JSON ou CSV. Le filtre browser accepte les clés de navigateur canoniques. Les revenus par navigateur sont alloués au prorata des impressions. La vue par navigateur peut être indisponible ou désactivée ; consultez /v1/stats/availability. Un regroupement ou un filtre par navigateur indisponible renvoie 400 breakdown_unavailable avec breakdown browser (JSON et CSV) avant les requêtes de statistiques. Le regroupement ou le filtrage par page_domain n'est disponible qu'une fois la mesure active : avant cela, il renvoie 400 `page_domain_unavailable`, et les réponses JSON contiennent `page_domain_available`. Avec un group_by contenant `hour`, la période (bornes incluses, jours ouvrés EST) doit être de 31 jours maximum, sinon 400 `hour_range` ; les revenus horaires des jours finalisés sont une allocation des revenus quotidiens (la réponse contient `hourly_revenue_allocated: true`), et non une mesure par heure ; les heures des jours non encore finalisés sont des estimations. En JSON, les heures sont en ISO UTC ; en CSV, elles s'affichent en EST (UTC-5). Chaque ligne a le statut estimated, reported, final ou mixed ; zéro impression valide donne un eCPM null. La réponse identifie le nombre accepté et l'instantané monétaire. Nécessite la portée publisher:read (clé API ou session web). Niveau de limite de débit : stats.

- Portée requise: `publisher:read`
- Limite débit: `stats` — 30 requêtes par fenêtre de 60 s par clé API ou session web

## Paramètres

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

## Réponse

```
{ 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 }
```

## Erreurs

Les routes soumises à une limite de débit renvoient `RateLimit-Limit`, `RateLimit-Remaining` et `RateLimit-Reset` (secondes avant la fin de la fenêtre) ; une réponse 429 contient aussi `Retry-After`. Ces en-têtes peuvent être absents lorsque le limiteur est temporairement indisponible (les requêtes sont alors acceptées).

| Statut | Sens |
|---|---|
| 401 | Clé API absente, invalide ou révoquée. |
| 403 | La clé n'a pas la portée requise, ou l'opération n'est pas autorisée pour cet acteur. |
| 429 | Limite de débit dépassée ; attendez `Retry-After` secondes. |
| 400 | Default Response |
| 404 | Default Response |
| 503 | Default Response |

## Exemples

### 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)
```

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