> AffiliateOS Help Center. Index of every article for AI tools: https://www.affiliateos.ai/help/llms.txt

# How to fetch offers from the Offer API

Offers and the feed · For publishers, networks · Updated 30 October 2026
Web version: https://www.affiliateos.ai/help/offers/fetch-every-offer

Call `GET https://affiliateos.xyz/publisher/offers` from your server, with your publisher key in the `x-api-key` header. You get every offer your account can run right now, priced at your payout, each with a [tracking link](https://www.affiliateos.ai/glossary#tracking-link) that already credits your account.

## Before you start

- A publisher [API key](https://www.affiliateos.ai/glossary#api-key). An owner or admin of your account makes one under **My Profile**, then **API Keys**. It starts with `pk_` and is shown once.
- A server to call from. The key lives in your server's environment, never in an app or a web page.

## Steps

### My Profile, then API Keys, then Generate Key

Type a name if you want one (the **Key name** field is optional), choose **Generate Key** and copy the key before you leave the page. Up to five keys can exist at once, so you can deploy a new key before you **Revoke** the old one.

### Call the Offer API

```bash
curl -G "https://affiliateos.xyz/publisher/offers" \
  -d country=US -d platform=iOS \
  -H "x-api-key: $AFFILIATEOS_KEY"
```

Send `country` on every call. It keeps offers your users can't be credited for off the list, and with one country it also merges copies of the same app that were aimed at different country lists.

### Read each row

A row is one offer. The fields you'll use first:

- `id`: the offer's ID. Key everything you store by it.
- `name`, `image` and `description`: what to show your user.
- `effectivePayoutUsd`: what the whole offer pays you, in USD.
- `goals`: each step, with what it pays you (`effectivePayoutUsd`) and the player's reward (`userRewardUsd`).
- `isPaidOnInstall`: `true` when the install is the step that pays you.
- `platforms` and `geoTargeting`: where the offer runs.
- `trackingUrl`: the link to send your user through.

```json
{
  "status": "success",
  "data": {
    "offers": [
      {
        "id": "aff_7c2e91b04d3a",
        "name": "Harbor Blocks",
        "platforms": ["ios"],
        "isPaidOnInstall": true,
        "effectivePayoutUsd": 4.2,
        "trackingUrl": "https://click.affiliateos.ai/click?off_id=aff_7c2e91b04d3a&pub_id=...&partner_id=...&sub_id={SUB_ID}&device_id={DEVICE_ID}",
        "goals": [
          {
            "name": "Install",
            "effectivePayoutUsd": 4.2,
            "userRewardUsd": 1.5,
            "userRewardIsAdvertiserSet": true
          },
          {
            "name": "Reach level 10",
            "effectivePayoutUsd": 0,
            "userRewardUsd": 1.5,
            "userRewardIsAdvertiserSet": true
          }
        ]
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 1,
      "total": 1,
      "has_more_pages": false
    }
  }
}
```

Example for Pebble Rewards, trimmed. Real rows carry every field in [Every offer field, explained](https://www.affiliateos.ai/help/offers/every-offer-field).

### Send each user through trackingUrl

Replace `{SUB_ID}` with that user's own ID and, when you have it, `{DEVICE_ID}` with the device's advertising ID. Leave `partner_id` exactly as we send it: it is what credits the conversion to you. The user's ID comes back on every [postback](https://www.affiliateos.ai/glossary#postback) as `sub_id`.

### Check it worked

The response reads `"status": "success"`, and without paging `pagination.total` equals the number of rows you got. Pick one row, search its `id` on the **Offers** page in the portal and check the payout matches.

## Filters and paging

Narrow the list with `country`, `platform` and the other filters in [Filter offers by country, platform and category](https://www.affiliateos.ai/help/offers/filter-by-country-platform-category). Paging is off unless you send `page` or `per_page`, so one response holds every offer. To turn it on, read [Paging and sorting a large list](https://www.affiliateos.ai/help/offers/paging-and-sorting).

## What the list leaves out

- **Offers that can't take a new user right now.** A daily cap that filled, or a budget that ran out or was paused. They come back on their own; no parameter brings them back sooner. See [Daily caps](https://www.affiliateos.ai/help/offers/daily-caps).
- **Extra copies of the same app.** With one `country` on the call, you get at most one install-paid and one event-paid row for each app and platform. See [How we pick which copy of an offer you see](https://www.affiliateos.ai/help/offers/which-copy-you-see).
- **Offers you hid.** If offer blocking is on for your account, an offer hidden with **Hide this offer from my list** also leaves this list and your Hosted Offerwall, and its link refuses new taps. What you already earned on it still pays.

## The Offers page reads the same list

The **Offers** page in the portal is built from this same list, at the same payouts, with two differences. It keeps offers that are full for today, marked **Capped for today**, and it matches copies of the same game more widely, so each game shows once per platform for each way it pays. An API key never gets capped rows: they would send your users to a dead end.

## For networks

A network uses the Network API: `GET https://affiliateos.xyz/network-api/offers` with the network's `ak_` key, made under **Workspace settings**, then **API Keys**, then **Generate Key**. The rows have the same core fields, with two differences:

- It pages by default, 50 offers a page. Follow `next_page` until `has_more_pages` is `false`.
- `pub_id` in each tracking link names your network. Leave it as we send it.

Every parameter and field is in the [Network API reference](https://www.affiliateos.ai/help/developers#network-api).

> **The key belongs on your server.** Anyone who has a `pk_` key can read your account through the API. In an app or a web page it can be copied. If one leaks, generate a new key, deploy it, then choose **Revoke** on the old one.