Daily Report API

For: SSP partners reconciling delivered impressions against billing.

A read-only HTTP endpoint that returns one row per UTC day with bid count, win count, impression count, and total CPM (USD) for your SSP. Backed by the RevoSurge ad-server's ClickHouse warehouse — same numbers we use for internal reporting.

In this article

• Endpoint and auth
• Parameters
• Response format
• Rate limit + caching
• Errors
• How to obtain a token
• FAQ

Endpoint

GET https://rtb-adaptor.revosurge.com/api/v1/ssp/{sspId}/report?from=YYYY-MM-DD&to=YYYY-MM-DD
Authorization: Bearer <jwt>

The {sspId} path variable must equal the sub claim in your token. A leaked token still requires knowing the exact sspId to read data, and a token can only ever return data for one SSP.

Authentication — tokens are issued by RevoSurge

Tokens are generated by the RevoSurge platform team and delivered to you.

• The signing secret is internal and never shared with partners.
• Do not attempt to sign your own tokens.
• A token has no expiry. It is valid until the secret is rotated, at which point we will issue you a fresh token.
• One token = one SSP. If you operate multiple SSP descriptor variants (e.g. kadum-adult, kadum-mainstream), one canonical token covers all variants under the same SSP family.

See How to obtain a token.

Parameters

Param	Where	Format	Notes
sspId	path	string	Must match your token's sub claim
from	query	YYYY-MM-DD	UTC date, inclusive
to	query	YYYY-MM-DD	UTC date, inclusive. Today's partial day is allowed
Authorization	header	Bearer <jwt>	Your assigned JWT

Window constraints:

• Inclusive: [from, to]
• Maximum: 7 days (to - from <= 6)
• from and to must be UTC dates (not timestamps)
• to cannot be after today UTC
• to may equal today (partial day, returns up-to-the-minute counts)

Response format

200 OK — JSON body:

{
  "ssp": "galaksion-mspush",
  "from": "2026-04-28",
  "to":   "2026-05-04",
  "currency": "USD",
  "days": [
    { "date": "2026-04-28", "bids": 14523, "wins": 8234, "imps": 7980, "totalCpmUsd": 432.18 },
    { "date": "2026-04-29", "bids": 16002, "wins": 9015, "imps": 8721, "totalCpmUsd": 471.55 },
    { "date": "2026-04-30", "bids":     0, "wins":    0, "imps":    0, "totalCpmUsd":   0.00 },
    { "date": "2026-05-01", "bids": 15741, "wins": 8870, "imps": 8612, "totalCpmUsd": 461.02 },
    { "date": "2026-05-02", "bids": 16188, "wins": 9114, "imps": 8851, "totalCpmUsd": 477.39 },
    { "date": "2026-05-03", "bids": 15997, "wins": 9001, "imps": 8745, "totalCpmUsd": 470.21 },
    { "date": "2026-05-04", "bids":  4521, "wins": 2412, "imps": 2333, "totalCpmUsd": 125.16 }
  ]
}

Field	Type	Meaning
ssp	string	Your SSP id (echo of the path variable)
from, to	string	UTC date range (echo of the query params)
currency	string	Always "USD"
days[].date	string	UTC date YYYY-MM-DD
days[].bids	integer	Bids issued by RevoSurge for this SSP (HTTP 200 bid responses)
days[].wins	integer	Win notifications received from this SSP
days[].imps	integer	Impressions actually recorded (impression-pixel events)
days[].totalCpmUsd	float	Sum of bid_price for wins / 1000, in USD

Days with zero activity are still present (counts = 0) so the array always has (to - from + 1) rows. Caller iterates without gaps.

Example call

curl "https://rtb-adaptor.revosurge.com/api/v1/ssp/galaksion-mspush/report?from=2026-04-28&to=2026-05-04" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOi...XYZ"

Rate limit + caching

• 10 requests/minute per token (jti bucket). Exceeding returns 429.
• Identical (sspId, from, to) queries are cached for 5 minutes server-side. Repeated queries inside that window do not hit the warehouse.
• Recommended polling cadence: once per hour or less. Daily totals don't change after the day closes.

Errors

Status	Cause
400	Bad date format (must be YYYY-MM-DD), window > 7 days, to < from, or to > today UTC
401	Missing token, bad signature, wrong issuer, or token's sub ≠ path {sspId}
429	Rate limit exceeded (10/min per token)
500	Internal error — retry after a short delay

Error body shape:

{ "error": "bad_window", "detail": "window exceeds 7 days (got 14)" }

How to obtain a token

Reach out via your existing communication channel with RevoSurge (Telegram, Microsoft Teams, or whichever channel you already use with your account manager) and share your SSP id (e.g. galaksion-mspush). We will:

1. Verify your identity and the SSP you operate.
2. Sign a long-lived JWT with the canonical SSP id as the sub claim.
3. Deliver the token back through the same channel.

Treat the token like a password:

• Do not commit it to source control.
• Store it in a secrets manager or environment variable.
• Restrict access to engineers who need to call the API.

Token rotation

If we rotate the signing secret (e.g. after a suspected leak):

1. All existing tokens stop working immediately. You will receive 401 on every request.
2. RevoSurge will issue you a fresh token via the same channel as the original delivery.
3. Replace the old token with the new one in your environment.

To request rotation proactively (e.g. you suspect your token has been exposed), notify us through the same Telegram / Teams channel you used to receive the original token.

FAQ

Why are my bid and win counts different from your billing report?

Three counts are returned for transparency:

• bids — bids RevoSurge issued (you may have rejected them in the auction).
• wins — win notifications you sent us (auction confirmation).
• imps — actual impressions recorded by our impression-pixel/event endpoint.

Wins and impressions can diverge by a few percent in either direction:

• Wins > imps if a win pixel doesn't fire (creative blocked, ad-blocker, network).
• Imps > wins in rare retry / multi-imp scenarios.

Use imps for billing reconciliation — it represents what was actually delivered.

Why does my SSP id show counts that look aggregated across descriptors?

Some SSP families (exoclick, kadam, traforama, daoad, etc.) operate multiple descriptor variants on our side (e.g. exoclick-banner, exoclick-pop). Our impression pipeline records the canonical SSP only (suffix stripped), while our bid pipeline records the full descriptor. The Daily Report API rolls up at the canonical level, so a token issued for exoclick returns the union of all exoclick-* activity.

If you require per-descriptor breakdown, raise a ticket — it requires a data-pipeline change on our side and is not currently supported by this endpoint.

How fresh is the data?

• Bids and wins appear within seconds of the auction.
• Impressions appear within seconds of the impression-pixel event.
• Late-arriving wins (notifications delayed by SSP) can shift counts by ~1% within the first 1-2 hours after midnight UTC. Counts stabilize after that.

Can I query more than 7 days at a time?

No. Issue multiple requests for adjacent 7-day windows. The 5-minute cache makes this efficient if you run a daily backfill job.

Currency

All totalCpmUsd values are USD. We do not convert to other currencies.