---
title: "Get Offers"
method: GET
path: "/v2/client/offers"
tags: ["Offers"]
---

# Get Offers

`GET /v2/client/offers`

Returns offers for the current user in one of two modes:
**Full catalog (default)** — Omit `offer_ids`. Behavior matches the historical user-based offers list (upstream AdGate user-based offers API). Optional query parameters such as `limit`, `is_game`, `ipad`, `devices`, `client_ip`, `client_user_agent`, `ios_id`, `android_advertiser_id`, `idfv`, `device_name`, `os_version`, and `in_app` apply to this mode. When provided, `client_ip`, `client_user_agent`, and the device/tracking parameters are appended to each offer's `click_url`.
**By offer IDs** — Include `offer_ids` as a comma-separated list of AdGate offer IDs (non-empty, duplicate IDs deduplicated). There is **no** BitLabs-enforced maximum ID count (subject to upstream AdGate limits). The response uses the same `OffersV2` schema; upstream calls use AdGate’s user-based “offers by IDs” API. Optional `tags` use the same encoding and merge semantics as catalog mode. List-scoping parameters (`limit`, `is_game`, `devices`, etc.) are ignored in this mode. Response order matches **AdGate** only; BitLabs does not reorder results.
Malformed `offer_ids`, empty `offer_ids`, or invalid `tags` yield **400 Bad Request**. The upstream `rank_method` parameter is not supported.

## Query parameters

- `devices` string[]
- `in_app` boolean, nullable
- `client_user_agent` string
- `client_ip` string
- `ios_id` string
- `android_advertiser_id` string
- `idfv` string
- `device_name` string
- `os_version` string
- `is_game` boolean, nullable
- `ipad` boolean, nullable
- `limit` integer
- `offer_ids` string
- `tags` string, URL-encoded query
- `bb_track` string

## Headers

- `User-Agent` string, required

## Response `200`

OK

- object
  - `data` OffersV2
    - `offers` OfferV2[], required
      - `id` integer, required
      - `anchor` string, required — Offer title to display to users
      - `description` string, required — Enter to win a Playstation 5!
      - `requirements` string, required — What the user should do to complete an offer
      - `confirmation_time` string, required — Text that described how long it takes to receive credit
      - `click_url` string, required — URL to redirect the user to
      - `support_url` string, required — The URL the user can access to get support in case they are not rewarded
      - `icon_url` string, required — Square icon URL
      - `impression_url` string, required — URL to notify that the offer was viewed
      - `categories` string[], required — An array of offer categories
      - `total_points` string, required — Total points the user may earn
      - `total_points_promotional` string — If a promotion is currently in progress, the amount of points they will earn. If not null, this should be used instead of total_points.
      - `is_sticky` boolean, required — If an offer should be pinned to the top of the offer wall
      - `events` OfferV2Event[], required — An array of events the user may complete to earn points. Each event is an object.
        - `uuid` string, required — ID of the event
        - `hash` string — Unique offer event hash.
        - `name` string, required — Event name to display to the user
        - `type` 'flat' | 'dynamic', required — Flat events have static point values. Dynamic events will have varying payouts.
        - `payable` boolean, required — Whether the event pays anything to the user
        - `display_type` 'none' | 'up_to' | 'commission', required — This determines how the potential points are displayed. "none": no special logic. User receives {points}. "up_to": display "Up to {points}". "commission": display "{points} per ${commission_amount}
        - `points` string, required — Will be 0 if the event is not payable.
        - `promotional_points` string — Points if there is an ongoing promotion. If not null, this should be used instead of points.
        - `commission_amount` string — For "commission", the points amount to use in the phrase above.
        - `payout` string — The dollar amount.
        - `status` 'viewed' | 'pending' | 'completed' | 'canceled', required
        - `type_id` integer, required — ID used to identify the event type. See all available Event IDs here: https://developer.bitlabs.ai/docs/offer-api#event-type-ids
        - `ttc_minutes` integer, required — Time to complete in minutes (if applicable).
        - `expires_at` integer, required — Expiration timestamp (if applicable).
        - `time_played` TimePlayed — Time played event details (if applicable).
          - `id` integer, required
          - `goal_unit` string, required
          - `goal_unit_count` integer, required
        - `multiple_conversions_allowed` boolean, required — Whether multiple conversions are allowed for this event.
        - `multiple_conversions_rules` MultipleConversionsRules — Rules for multiple conversions (if applicable).
          - `rule_type` 'unlimited' | 'interval' — "unlimited": The offer event can be completed an indefinite amount of times without time limit. "interval": The offer event can be completed a certain amount of times in a given amount of time.
          - `x_conversions` integer — Number of conversions allowed when rule_type is "interval".
          - `every_y_seconds` integer — Time interval in seconds when rule_type is "interval".
        - `timestamp` integer — Event timestamp (if applicable).
      - `app_metadata` OfferV2AppMetadata, required
        - `app_id` string — The app ID
        - `categories` string[], required — The categories the app belongs to
        - `screenshot_urls` string[], required — URLs to screenshots of the app
        - `video_urls` string[], required — URLs to videos of the app
      - `is_game` boolean, required — Indicates if the offer is a game. If true, the offer is a game. If false, the offer is not a game.
      - `stats` OfferV2Stats, required
        - `tool_cpm` string — The tool CPM for this offer
        - `network_cpm` string — The network CPM for this network
      - `disclaimer` string, required — A disclaimer that should be shown to the user before they start the offer.
      - `pending_time` integer, required — Time in minutes that a reward will be held from the user completion
      - `web_to_mobile` boolean, required — Whether this offer must be accessed on the user's mobile device.
      - `web_to_mobile_devices` string[], required — Array of devices the users must access the user on. The list of applicable devices is taken from the devices stored for that particular user
      - `epc` string — Network-wide EPCs
      - `session_hours` integer, required — Offer is valid for that many hours
      - `offer_expires_at` string, date-time — Offer expiration timestamp
      - `product_id` string, required — A unique string shared between offers which belong to same product, e.g. same mobile app.
      - `product_name` string, required — The offer's product name.
      - `things_to_know` string[], required — List of key points the user should be aware of regarding the offer such as prerequisites or limitations.
      - `creatives` OfferV2Creatives — Creative assets for the offer.
        - `icon` string — Deprecated: Use creatives.icon instead. This field will be removed in a future version.
        - `images` object — Creative assets for the offer in different sizes.
      - `mobile_verification_required` boolean, required — Indicates if mobile verification is required for this offer.
      - `funnel_id` string, required — Funnel identifier for the offer.
      - `lowest_cap_left` integer, nullable — The lowest cap left for the offer, indicating remaining capacity.
      - `arpu_goals` OfferV2ArpuGoal[] — ARPU (Average Revenue Per User) goals for the offer, specifying daily targets in dollars.
        - `day` integer, required — The day number for the ARPU goal.
        - `goal` string, required — The goal amount in dollars for the specified day.
    - `started_offers` OfferStartedV2[], required
      - `id` integer, required
      - `anchor` string, required — Offer title to display to users
      - `description` string, required — Enter to win a Playstation 5!
      - `requirements` string, required — What the user should do to complete an offer
      - `confirmation_time` string, required — Text that described how long it takes to receive credit
      - `support_url` string, required — The URL the user can access to get support in case they are not rewarded
      - `icon_url` string, required — Square icon URL
      - `categories` string[], required
      - `total_points` string, required — Total points the user may earn
      - `total_points_promotional` string — If a promotion is currently in progress, the amount of points they will earn. If not null, this should be used instead of total_points.
      - `events` OfferV2Event[], required — An array of events the user may complete to earn points. Each event is an object.
        - `uuid` string, required — ID of the event
        - `hash` string — Unique offer event hash.
        - `name` string, required — Event name to display to the user
        - `type` 'flat' | 'dynamic', required — Flat events have static point values. Dynamic events will have varying payouts.
        - `payable` boolean, required — Whether the event pays anything to the user
        - `display_type` 'none' | 'up_to' | 'commission', required — This determines how the potential points are displayed. "none": no special logic. User receives {points}. "up_to": display "Up to {points}". "commission": display "{points} per ${commission_amount}
        - `points` string, required — Will be 0 if the event is not payable.
        - `promotional_points` string — Points if there is an ongoing promotion. If not null, this should be used instead of points.
        - `commission_amount` string — For "commission", the points amount to use in the phrase above.
        - `payout` string — The dollar amount.
        - `status` 'viewed' | 'pending' | 'completed' | 'canceled', required
        - `type_id` integer, required — ID used to identify the event type. See all available Event IDs here: https://developer.bitlabs.ai/docs/offer-api#event-type-ids
        - `ttc_minutes` integer, required — Time to complete in minutes (if applicable).
        - `expires_at` integer, required — Expiration timestamp (if applicable).
        - `time_played` TimePlayed — Time played event details (if applicable).
          - `id` integer, required
          - `goal_unit` string, required
          - `goal_unit_count` integer, required
        - `multiple_conversions_allowed` boolean, required — Whether multiple conversions are allowed for this event.
        - `multiple_conversions_rules` MultipleConversionsRules — Rules for multiple conversions (if applicable).
          - `rule_type` 'unlimited' | 'interval' — "unlimited": The offer event can be completed an indefinite amount of times without time limit. "interval": The offer event can be completed a certain amount of times in a given amount of time.
          - `x_conversions` integer — Number of conversions allowed when rule_type is "interval".
          - `every_y_seconds` integer — Time interval in seconds when rule_type is "interval".
        - `timestamp` integer — Event timestamp (if applicable).
      - `latest_date` string, date-time, required — Date of the latest click or conversions.
      - `points` string, required — Will be 0 if the event is not payable.
      - `completed_events` integer, required
      - `completed` boolean, required
      - `has_pending_conversions` boolean, required
      - `disclaimer` string, required
      - `app_metadata` OfferV2AppMetadata, required
        - `app_id` string — The app ID
        - `categories` string[], required — The categories the app belongs to
        - `screenshot_urls` string[], required — URLs to screenshots of the app
        - `video_urls` string[], required — URLs to videos of the app
      - `hours_left` integer, required — Number of hours left for the offer to be completed
      - `continue_url` string, required — URL to redirect the user to
      - `is_game` boolean, required — Indicates if the offer is a game. If true, the offer is a game. If false, the offer is not a game.
    - `offerwall_code` string, required

---

[API](https://skmtc.net/bitlabs/apis/bitlabs-client-api.md) · [All operations](https://skmtc.net/bitlabs/apis/bitlabs-client-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitlabs/bitlabs-client-api/revisions/99209a6285bf/schema)