Get demand statistics

GET/demands/stats

Required scope: rtb:demand:read

Authenticate with Authorization: Bearer YOUR_NEXUS_API_KEY. The legacy token query parameter remains available; use one transport per request.

Authentication and error codes →

Query parameters

Parameter	Required	Description
token	Only without Bearer	Compatibility transport for an active member key with explicit rtb:demand:read. Prefer the Authorization header; do not send both.
dsp	Yes	Granted demand/DSP ID, integer from 1 to 2147483647.
date_from	Yes	Inclusive UTC start day, YYYY-MM-DD.
date_to	Yes	Inclusive UTC end day, YYYY-MM-DD; maximum 90 days per request.
groupBy	No	Only day is supported (default).
export	No	json (default) or csv.

cURL

curl --get "https://api.example.com/demands/stats" \
  --header "Authorization: Bearer YOUR_NEXUS_API_KEY" \
  --data-urlencode "dsp=7" \
  --data-urlencode "date_from=2026-10-28" \
  --data-urlencode "date_to=2026-10-28"

JavaScript

const params = new URLSearchParams({ dsp: '7', date_from: '2026-10-28', date_to: '2026-10-28' });
const response = await fetch(`https://api.example.com/demands/stats?${params}`, {
  headers: { Authorization: `Bearer ${process.env.NEXUS_API_KEY}` },
});
if (!response.ok) throw new Error(`Nexus returned ${response.status}`);
console.log(await response.json());

Python

import os
import requests

response = requests.get(
    'https://api.example.com/demands/stats',
    headers={'Authorization': f"Bearer {os.environ['NEXUS_API_KEY']}"},
    params={'dsp': 7, 'date_from': '2026-10-28', 'date_to': '2026-10-28'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

{
  "status": "success",
  "message": "Demand Stats report",
  "data": [
    {
      "date": "2026-10-28",
      "dsp": 7,
      "requests": "1000",
      "requests_valid": "900",
      "requests_error": "100",
      "impressions": "100",
      "clicks": "5",
      "spend": 0.5,
      "cpc": "0.1000",
      "ctr": "5.00%",
      "win": "10.00",
      "cpm": "5.0000",
      "sync": "50.00"
    }
  ]
}

requests is valid requests plus request errors. Summed counts are exact decimal strings. Demand spend is SUM(aff_price) / 1000000 in the source's native reporting currency, returned as a number; no currency conversion occurs. The positive DSP ID must match the requested grant.

CPC, CTR, win rate, and CPM use the exchange metric formulas. sync is SUM(requests_sync) / total requests times 100, formatted to two decimals without %. Non-positive numerators or denominators use 0.00 (0.00% for CTR).

Use export=csv for an attachment with the same fields and spreadsheet-formula protection. The final UTC day includes fractional seconds. Empty periods return 404 for JSON and CSV.

Errors and limits

The exchange errors and limits apply here too. Grants are re-read from the authenticated tenant's members.extra.demands on every request; query parameters cannot select another account. Responses are non-cacheable.