Reporting API

Your statistics with us, by API: requests, bids, wins, impressions and money, by day or hour, in your time zone. The same API works for publishers (SSP) and advertisers (DSP); a key sees only its own feed.

Quick start

curl -X POST 'https://api.gfybid.com/api/v1/report' \
  -H 'X-API-Token: your_api_token_here' \
  -H 'Content-Type: application/json' \
  --data '{
    "date_from": "2026-11-01 00:00:00",
    "date_to": "2026-11-04 23:59:59",
    "group_by": ["EventDate"],
    "metrics": ["Requests", "Bids", "Impression", "Amount", "Ecpm"],
    "timezone": "UTC",
    "order": {"field": "EventDate", "sort": "DESC"},
    "page": {"number": 1, "size": 100}
  }'

Authentication

Every request carries your API key in a header:

X-API-Token: {your key}
Content-Type: application/json

• How to get a key: ask your account manager. A key is shown once — store it safely.
• A key belongs to one feed and sees only that feed's statistics.
• Authorization: Bearer {your key} is accepted as well.
• Lost or leaked key: ask for a new one; the old one is revoked at once. You can have several keys (for example, one per system).

Endpoint

POST https://api.gfybid.com/api/v1/report

Request body

Unknown fields are refused with 422, so a typo never silently changes your report.

Metrics

Time and freshness

• Statistics are updated every minute.
• Impressions and money are dated by the time of the bid, not of the billing notice.
• Traffic counters are hourly. In time zones with a 30- or 45-minute offset, hour boundaries follow UTC hours.
• Only periods with data are returned: a day or hour without traffic has no row.

Response

{
  "meta": {
    "pagination": {"per_page": 100, "current_page": 1, "has_more": false},
    "role": "ssp",
    "status": true,
    "code": 200,
    "currency": "USD",
    "timezone": "UTC"
  },
  "data": [
    {
      "metric": {
        "Requests": "1250000",
        "Bids": "310000",
        "Impression": "41020",
        "Amount": "1590.776",
        "Ecpm": "0.038781"
      },
      "group": {
        "EventDate": {"id": "2026-11-04", "name": "2026-11-04", "field_name": "EventDate"}
      }
    }
  ]
}

• Values are strings. Counts are integers; money is a decimal in USD with up to 6 decimals.
• meta.role is ssp or dsp — the side of your key.
• With EventHour, the group id looks like 2026-11-04 13:00. Without group_by, group is an empty object.
• Page through the result with page.number while meta.pagination.has_more is true.

The numbers above are an example, not real data.

Example: hours of one day, in Berlin time

{
  "date_from": "2026-11-04 00:00:00",
  "date_to": "2026-11-04 23:59:59",
  "group_by": ["EventHour"],
  "metrics": ["Requests", "Impression", "Amount"],
  "timezone": "Europe/Berlin",
  "page": {"number": 1, "size": 24}
}

Limits

• At most 2 requests per second per key, with bursts up to 10.
• A period of at most 31 days per request.
• Up to 100 rows per page.
• The same report (any page) is served from a cache for 2 minutes, so paging is fast and cheap.

Errors

{
  "meta": {"status": false, "code": 422},
  "error": "the period must not exceed 31 days"
}

Common 422 messages