Ads reporting

Pozy syncs the performance of every ad on every connected ad account, whether it was created through Pozy or in the network's own ads manager. Most reporting reads those synced numbers and costs nothing on the network's side. When you need something the sync does not hold, such as an age split or a custom Google query, Pozy asks the network live.

#Pick the right call

Network-specific reports live on their pages: Google's search terms and keyword planner in Google Ads, LinkedIn firmographics in LinkedIn Ads.

#Build a dashboard

GET /v1/ads/tree returns campaigns with their ad sets and ads nested inside, each with a metrics object for the date range. Filter and sort it like a report.

curl "https://api.pozy.ai/v1/ads/tree?accountId=66b2e19d8c3f5a7e9d0b1c2e&fromDate=2027-01-01&toDate=2027-01-31&hasDelivery=true&sort=spend_desc&compare=previous" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/ads/tree?accountId=66b2e19d8c3f5a7e9d0b1c2e&fromDate=2027-01-01&toDate=2027-01-31&hasDelivery=true&sort=spend_desc&compare=previous", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
for (const c of data.campaigns) console.log(c.campaignName, c.metrics?.spend, c.metrics?.roas);

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/ads/tree",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "accountId": "66b2e19d8c3f5a7e9d0b1c2e",
        "fromDate": "2027-01-01",
        "toDate": "2027-01-31",
        "hasDelivery": "true",
        "sort": "spend_desc",
        "compare": "previous",
    },
)
for c in resp.json()["campaigns"]:
    print(c["campaignName"], c.get("metrics", {}).get("spend"))

Useful filters on the tree: platform, status, adAccountId, profileId, campaignId, search, minSpend, hasDelivery, updatedSince and source (pozy for ads created through Pozy, all by default). compare=previous adds the same metrics for the period just before, for "vs last month" views. timeIncrement=1 with dailyLevel (campaign, adset or ad) adds a daily series at that level.

For an account-level chart, GET /v1/ads/timeline?accountId=... returns one row per day with spend, impressions, reach, clicks, engagement, conversions and the derived rates.

#One ad over time

GET /v1/ads/{adId}/analytics returns a summary for the range and a daily series.

curl "https://api.pozy.ai/v1/ads/66f0a1b2c3d4e5f6a7b8c9d0/analytics?fromDate=2027-01-04&toDate=2027-01-31&breakdowns=age,gender" \
  -H "Authorization: Bearer $POZY_API_KEY"

{
  "backfillPending": false,
  "ad": { "id": "66f0a1b2c3d4e5f6a7b8c9d0", "name": "Spring sale", "platform": "facebook", "status": "active", "currency": "USD" },
  "analytics": {
    "summary": { "spend": 412.6, "impressions": 98100, "reach": 61200, "clicks": 1530, "ctr": 1.56, "cpc": 0.27, "cpm": 4.21, "conversions": 38, "costPerConversion": 10.86, "purchaseValue": 2140.0, "roas": 5.19 },
    "daily": [{ "date": "2027-01-04", "spend": 14.9, "impressions": 3400, "clicks": 51 }],
    "breakdowns": { "age": [{ "value": "25-34", "spend": 168.2, "impressions": 40100 }] }
  }
}

#Breakdowns

breakdowns takes a comma-separated list. Each dimension is one live call to the network, so ask only for what you show.

A dimension no network defines returns 400 listing the valid ones. A dimension from another network (say age on a LinkedIn ad) is accepted and dropped, and the response has no breakdowns object. LinkedIn returns firmographics for the whole range only, with no daily split, lags 12 to 24 hours and hides segments with fewer than 3 events.

#Metrics

Every metrics and summary object uses the same names on every network. Money is in the ad account's currency, in whole units.

On Meta, the same purchase often shows under several action keys (a pixel key, an omni_ key and a plain one). Prefer the offsite_conversion.fb_pixel_* keys, or read conversions and purchaseValue, which already pick one.

#What each network reports

#Date ranges and history

• Without fromDate and toDate, ranges default to the last 90 days. The longest range is 730 days.
• When an ad account connects, Pozy imports its last 90 days. Synced summaries hold nothing before that.
• On Meta, asking for older days answers 202 with backfillPending: true and the part already covered, while Pozy imports the rest (up to 730 days back) in the background. Repeat the request until it returns 200. Other networks never return 202.
• Breakdowns and live queries read the network directly, so they are not limited by the import.
• Days follow the ad account's time zone.

#Currencies

Pozy never converts currencies. Each campaign node and timeline row carries currency. When one connection's ad accounts bill in different currencies, the timeline returns one row per currency per day. Do not add spend across them.

#Attribution

Each network counts a conversion against an ad within its own windows, so numbers differ between networks for the same sale.

#Live queries

GET /v1/ads/insights passes your query to the network and returns its rows as they come. The connection's platform decides which parameters apply, and validation is the network's: an unknown field returns 400 with the network's message.

curl -G https://api.pozy.ai/v1/ads/insights \
  -H "Authorization: Bearer $POZY_API_KEY" \
  --data-urlencode "accountId=66b2e19d8c3f5a7e9d0b1c2f" \
  --data-urlencode "query=SELECT campaign.name, metrics.cost_micros, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS"

Google returns its own units, so cost_micros divides by 1,000,000, and counters arrive as strings. Selecting segments.date needs a finite date filter.

#Reach across several campaigns on TikTok

Adding the reach of two campaigns counts a person who saw both twice. To count each person once, filter the set and group by country instead of by campaign:

dataLevel=AUCTION_CAMPAIGN&dimensions=country_code&metrics=reach,impressions,frequency
&fromDate=2027-01-01&toDate=2027-01-31
&filtering=[{"field":"campaign_ids","operator":"IN","value":["1876574798182050","1876575504573650"]}]

Reach is then per country; adding countries together double counts people reached in both. Filter at the same level as dataLevel or a coarser one.

#Long reports on Meta

For long ranges or many accounts, submit a background job with the same fields as a live Meta query:

curl -X POST https://api.pozy.ai/v1/ads/insights/reports \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "66b2e19d8c3f5a7e9d0b1c2e", "objectId": "act_1234567890", "level": "ad", "fields": "ad_name,spend,impressions,actions", "fromDate": "2026-01-01", "toDate": "2026-12-31", "timeIncrement": "monthly" }'

It answers 202 with a reportRunId. Poll GET /v1/ads/insights/reports/{reportRunId}: it reports status and percentCompletion while it runs, and once status is Job Completed it returns the rows, paged with limit and after.

#Know when numbers are stale

Subscribe to these webhook events instead of polling sync state:

A failed initial sync is not final: running the ads connect flow again queues the import again. Reconnecting fixes token_invalid, permission_denied and rate_limited; no_ad_accounts needs the person to have an ad account first.

#Endpoints

#Webhook events