# RTB Inbounds API RTB Inbounds is the log of inbound [Real-Time Bidding](/api/real-time-bidding-rtb) 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](/guides/how-to-use-the-rtb-log-troubleshooting-and-optimizing) 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](/api/exports) instead. ## RTB Inbound object ```json { "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 } ``` ### Fields | Field | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `call_uuid` | UUID of the [Call](/api/calls) 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](/api/real-time-bidding-rtb#retreaver-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](/api/payout-bid-modification-tables) is enabled for the campaign's company. | > [!NOTE] > UUID fields on RTB Inbounds and their [Exports](/api/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 ```shell curl "https://api.retreaver.com/api/v5/rtb_inbounds.json?api_key=[api_key]&campaign_id[]=123&created_at=last_7d" ``` > The above command returns JSON structured like this: ```json { "rtb_inbounds": [ { "call_uuid": "3d745a09-6e2b-4b8f-9e7d-9a2f6a9d9d21", "uuid": "8f0a2d13-9d3a-4b3e-9a7a-6b8e4b9d9a21", "status": "claimed", "revenue": 12.5, "payout": 8.75 } ] } ``` Each element is an [RTB Inbound object](#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](/api/introduction#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 ```shell curl "https://api.retreaver.com/api/v5/rtb_inbounds.json?api_key=[api_key]" ``` The endpoint is versioned like the rest of the API; `v2`, `v3`, `v4` and `v5` all serve the same data. ### Query Parameters | 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](/api/postback-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. |