Ads · Reach and Frequency
Creates a reach-frequency prediction. Works with Meta Ads.
POST
https://api.pozy.ai/v1/ads/rf-predictionsFacebook and InstagramcreateRfPrediction
Guide: Meta Ads
Request
Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Keys with the ads resource group disabled get 403 resource_group_disabled. Authentication
Request body
application/json, required
accountIdstringrequiredadAccountIdstringrequiredbudgetAmountnumberreachintegerstartDatestring (date-time)requiredendDatestring (date-time)requiredfrequencyCapinteger1 to 90.
targetingobjectplacementsobject
Example
curl -X POST "https://api.pozy.ai/v1/ads/rf-predictions" \
-H "Authorization: Bearer $POZY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "696e0b682d0a31188e7a2ba9",
"adAccountId": "666219aad7bab67ace411e4f",
"startDate": "2026-10-02T09:00:00.000Z",
"endDate": "2026-10-02T09:00:00.000Z"
}'const res = await fetch("https://api.pozy.ai/v1/ads/rf-predictions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.POZY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
accountId: "696e0b682d0a31188e7a2ba9",
adAccountId: "666219aad7bab67ace411e4f",
startDate: "2026-10-02T09:00:00.000Z",
endDate: "2026-10-02T09:00:00.000Z"
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);import os
import requests
resp = requests.post(
"https://api.pozy.ai/v1/ads/rf-predictions",
headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
json={
"accountId": "696e0b682d0a31188e7a2ba9",
"adAccountId": "666219aad7bab67ace411e4f",
"startDate": "2026-10-02T09:00:00.000Z",
"endDate": "2026-10-02T09:00:00.000Z",
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())Response
201 on success
adAccountIdstringcurrencystringpredictionobject13 child fields
predictionIdstringstatusstringbudgetnumberCan be null.
reachintegerCan be null.
impressionsintegerCan be null.
minBudgetnumberCan be null.
maxBudgetnumberCan be null.
minReachintegerCan be null.
maxReachintegerCan be null.
frequencyCapintegerCan be null.
startTimeintegerCan be null.
stopTimeintegerCan be null.
expiresAtstringCan be null.
201 response
{
"adAccountId": "666219aad7bab67ace411e4f",
"currency": "USD",
"prediction": {
"predictionId": "67efcfc573f55bdb3de39dd1",
"status": "active",
"budget": 12.5,
"reach": 1,
"impressions": 1,
"minBudget": 12.5,
"maxBudget": 12.5,
"minReach": 1,
"maxReach": 1,
"frequencyCap": 1,
"startTime": 1,
"stopTime": 1,
"expiresAt": "2026-10-02T09:00:00.000Z"
}
}Errors
Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:
| 400 | invalid_request_error | A parameter or body field is missing or invalid. param names it. |
| 401 | authentication_error | The API key is missing, revoked or expired. |
| 403 | permission_error | The key is read-only, scoped to other profiles, or has this resource group disabled. |
| 429 | rate_limit_error | Too many requests this minute. Wait for Retry-After seconds. |
Every code is listed in Errors.