RTB Inbounds API

RTB Inbounds is the log of inbound Real-Time Bidding reservations: one row per RTB ping your campaigns received, whether it was claimed, expired, rejected, or found no target. It is the same data as the RTB Dashboard in your account.

This endpoint returns a live, filtered page of recent rows. To pull a large historical range as a single file, use Exports instead.

RTB Inbound object

{
  "call_uuid": "3d745a09-6e2b-4b8f-9e7d-9a2f6a9d9d21",
  "uuid": "8f0a2d13-9d3a-4b3e-9a7a-6b8e4b9d9a21",
  "postback_key_id": 456,
  "caller_number": "+15551234567",
  "affiliate_id": 789,
  "campaign_id": 123,
  "target_id": 321,
  "revenue": 12.5,
  "payout": 8.75,
  "status": "claimed",
  "duplicate_order": 0,
  "duplicate_original_uuid": "00000000-0000-0000-0000-000000000000",
  "caller_state": "TX",
  "caller_city": "Austin",
  "caller_zip": "78701",
  "caller_country": "US",
  "created_at": "2026-09-01T14:02:11Z",
  "confirmed_at": "2026-09-01T14:02:12Z",
  "ended_at": "2026-09-01T14:05:41Z",
  "time_to_resolve": 1.2,
  "fired_pixels_count": 2,
  "fired_pixels_error_count": 0,
  "pbm_table_version": "7",
  "pbm_rule_id": 2,
  "pbm_bucket": 6231,
  "pbm_variant": "treatment",
  "pbm_original_payout": 10.0,
  "pbm_percent_of_revenue": 70
}

Swipe horizontally for full code

Fields

Swipe horizontally to view full table

Field	Description
`call_uuid`	UUID of the Call this reservation belongs to — the join key back to Calls. It is not the same value as this reservation’s own `uuid`. Not every reservation results in a Call (a `rejected` or `no-target` ping, for example); when there is none, this is the all-zero UUID, not `null`.
`uuid`	This reservation’s own identifier.
`affiliate_id` / `campaign_id` / `target_id`	Retreaver’s internal IDs for the publisher, campaign, and target.
`status`	One of `expired`, `claimed`, `no-target`, `rejected` (plus some internal Ping Shield statuses).
`revenue` / `payout`	Dollar amounts for this reservation.
`time_to_resolve`	Seconds between the ping and its resolution.
`duplicate_original_uuid`	UUID of the original reservation this one duplicates. Otherwise the all-zero UUID, never `null`.
`pbm_*`	Present only when Payout Bid Modification is enabled for the campaign’s company.

Note

UUID fields on RTB Inbounds and their Exports are never null. An absent UUID is always the all-zero sentinel 00000000-0000-0000-0000-000000000000, so compare against that string rather than checking for null or blank.

List RTB Inbounds

curl "https://api.retreaver.com/api/v5/rtb_inbounds.json?api_key=[api_key]&campaign_id[]=123&created_at=last_7d"

Swipe horizontally for full code

The above command returns JSON structured like this:

{
  "rtb_inbounds": [
    { "call_uuid": "3d745a09-6e2b-4b8f-9e7d-9a2f6a9d9d21", "uuid": "8f0a2d13-9d3a-4b3e-9a7a-6b8e4b9d9a21", "status": "claimed", "revenue": 12.5, "payout": 8.75 }
  ]
}

Swipe horizontally for full code

Each element is an RTB Inbound object, abbreviated above. Results are always returned 100 per page; per_page is not configurable on this endpoint. Like every paginated index in this API, responses carry a Link header — see Paginated.

You can only filter by IDs (campaign, affiliate, target, postback key) your api_key’s account already has access to. Any other IDs are silently dropped from the filter.

HTTP Request

curl "https://api.retreaver.com/api/v5/rtb_inbounds.json?api_key=[api_key]"

Swipe horizontally for full code

The endpoint is versioned like the rest of the API; v2, v3, v4 and v5 all serve the same data.

Query Parameters

Swipe horizontally to view full table

Parameter	Type	Description
`api_key`	string	Required. The API key used to authenticate this request.
`campaign_id[]`	integer array	Restrict to one or more of your campaigns.
`affiliate_id[]`	integer array	Restrict to one or more publishers (Sources).
`target_id[]`	integer array	Restrict to one or more targets (Call Endpoints).
`postback_key_id[]`	integer array	Restrict to one or more postback (RTB) keys.
`status[]`	string array	One or more of `expired`, `claimed`, `no-target`, `rejected`.
`duplicate`	boolean	`true` or `false` — restrict to duplicate (or non-duplicate) reservations.
`caller_state`	string	Two-letter US state or Canadian province abbreviation.
`caller_country`	string	Two-letter country abbreviation.
`revenue[]`	[min, max]	Two-element range, e.g. `revenue[]=20&revenue[]=30`.
`payout[]`	[min, max]	Two-element range, same shape as `revenue[]`.
`created_at`	string	A relative window, e.g. `last_7d`. Takes precedence over the explicit bounds below.
`created_at_start`	datetime	Explicit range start (ISO 8601). Ignored if `created_at` is present.
`created_at_end`	datetime	Explicit range end (ISO 8601). Ignored if `created_at` is present. The window between start and end can’t exceed 2 months.
`page`	integer	Page number. Defaults to `1`.
`with_filters`	boolean	When `true`, the response also includes a `filters` object listing every valid campaign, publisher, target, postback key and status value for your account — handy for building a picker without paging those resources separately.