Developers

Caps API

Check how much room is left on an offer before you send traffic. Returns your personal cap, per-country backend caps, and the network-wide global cap — each with live usage and remaining amounts.

Endpoint

bash

GET https://taprain.com/api/v1/caps

Returns the cap data for a single offer, scoped to your account. Only caps that are actually configured appear in the response — an offer with no global cap simply omits the globalCap field.

Authentication

Pass your API key as a query parameter.

This is the same API key used by the Stats API, shown on your dashboard (Stats API button) and fetchable via GET /api/v1/api-key.

Query param

?apiKey=your_key_here

Warning

The Caps API accepts the key as a query parameter only. Call it server-side — never from client code where the key would be exposed in the page or browser history.

Parameters

All parameters are passed as URL query string values.

apiKey

stringrequired

Your API key. Same key as the Stats API.

offerName

stringrequired

The offer key (the short identifier shown below the offer name in the offer modal). Case-insensitive.

country

string

Optional ISO 3166-1 alpha-2 code (e.g. US, NZ) to filter per-country and personal caps to a single country.

Rate limit: 10 requests / minute per API key. Cap counters reset daily at midnight Eastern Time.

Response Fields

Only configured caps are included; absent caps are omitted.

globalCap

object

Network-wide cap across all publishers (if enabled): { type, limit, used, remaining }. type is "revenue" or "conversions".

countryCaps

array

Per-country backend caps: [{ country, type, limit, used, remaining }]. Present only for countries that have a cap.

userCap

object

Your personal cap for a non-per-country offer: { limit, used, remaining, measureType }. Returned when there's a single, non-device-split cap.

userCaps

array

Your personal caps when the offer is per-country and/or your cap is device-split: [{ country?, device?, limit, used, remaining, measureType }].

Note

measureType tells you whether a personal cap counts conversions or revenue. remaining is never negative — it floors at 0 once a cap is hit.

Example Requests

cURL

bash

curl "https://taprain.com/api/v1/caps?apiKey=YOUR_API_KEY&offerName=freecash-cpi"

cURL: single country

bash

curl "https://taprain.com/api/v1/caps?apiKey=YOUR_API_KEY&offerName=freecash-cpi&country=US"

JavaScript

const res = await fetch(
  'https://taprain.com/api/v1/caps?apiKey=YOUR_API_KEY&offerName=freecash-cpi'
);
const caps = await res.json();

if (caps.userCap && caps.userCap.remaining <= 0) {
  console.log('Personal cap reached — pause traffic.');
}
if (caps.globalCap) {
  console.log('Network remaining:', caps.globalCap.remaining);
}

Python

bash

import requests

resp = requests.get(
    'https://taprain.com/api/v1/caps',
    params={'apiKey': 'YOUR_API_KEY', 'offerName': 'freecash-cpi'},
)
caps = resp.json()
user = caps.get('userCap')
if user:
    print(f"{user['remaining']} / {user['limit']} {user['measureType']} left")

Example Response

A per-country offer with a global cap and a personal cap.

JSON

{
  "offerName": "freecash-cpi",
  "displayName": "Freecash Web CPE",
  "globalCap": {
    "type": "revenue",
    "limit": 5000,
    "used": 1320.5,
    "remaining": 3679.5
  },
  "countryCaps": [
    { "country": "US", "type": "revenue", "limit": 2000, "used": 880, "remaining": 1120 },
    { "country": "GB", "type": "revenue", "limit": 750,  "used": 750, "remaining": 0 }
  ],
  "userCaps": [
    { "country": "US", "limit": 100, "used": 23, "remaining": 77, "measureType": "conversions" },
    { "country": "GB", "limit": 50,  "used": 50, "remaining": 0,  "measureType": "conversions" }
  ]
}

For a simple (non-per-country) offer with a single personal cap, the personal cap is returned as userCap instead of the userCaps array:

JSON

{
  "offerName": "kashkick",
  "displayName": "KashKick",
  "userCap": { "limit": 200, "used": 41, "remaining": 159, "measureType": "conversions" }
}

Error Codes

HTTP responses

200

Success. Cap data returned (only configured caps are included).

400

Bad Request

Missing offerName parameter.

401

Unauthorized

Missing apiKey, or the key does not match an account.

404

Not Found

No active offer matches offerName.

429

Rate Limited

More than 10 requests/minute. Wait and retry.

500

Server Error

Internal error. Try again shortly.