Ads · Ad Insights

Flexible live insights query

Returns the flexible live insights query, one page at a time. Works with Meta Ads, Google Ads and TikTok Ads.

GEThttps://api.pozy.ai/v1/ads/insights

Facebook and Instagram, Google Workspace and TikTokqueryAdInsights

Guides: Meta Ads, TikTok Ads, Ads reporting

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the ads resource group disabled get 403 resource_group_disabled. Authentication

Query parameters

Name	Type	Notes
`accountId`required	string
`objectId`	string
`query`	string	Up to 10000 characters
`adAccountId`	string
`reportType`	string	One of `BASIC`, `AUDIENCE`Default `BASIC`
`dataLevel`	string	One of `AUCTION_ADVERTISER`, `AUCTION_CAMPAIGN`, `AUCTION_ADGROUP`, `AUCTION_AD`
`dimensions`	string
`metrics`	string
`page`	integer	Default `1`At least 1
`pageSize`	integer	Default `100`1 to 1000
`customerId`	string
`pageToken`	string
`level`	string	One of `ad`, `adset`, `campaign`, `account`
`fields`	string
`breakdowns`	string
`actionBreakdowns`	string
`actionAttributionWindows`	string
`actionReportTime`	string
`useUnifiedAttributionSetting`	boolean
`filtering`	string
`datePreset`	string
`fromDate`	string (date)
`toDate`	string (date)
`timeIncrement`	string
`limit`	integer	Default `25`1 to 500
`after`	string

Example

curl -X GET "https://api.pozy.ai/v1/ads/insights?accountId=696e0b682d0a31188e7a2ba9&limit=25" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/ads/insights?accountId=696e0b682d0a31188e7a2ba9&limit=25", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
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.get(
    "https://api.pozy.ai/v1/ads/insights",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "accountId": "696e0b682d0a31188e7a2ba9",
        "limit": 25,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

objectIdstring
adAccountIdstring
customerIdstring
fieldMaskstring
Can be null.
dataarray of object
pagingobject
- afterstring
  Can be null.
- nextPageTokenstring
  Can be null.
- pageinteger
- pageSizeinteger
- totalRowsinteger
- totalPagesinteger

200 response

{
  "objectId": "6cd1b53a19a7e157d2d46b68",
  "adAccountId": "666219aad7bab67ace411e4f",
  "customerId": "691909ff82eb5ed7c816716d",
  "fieldMask": "string",
  "data": [
    {}
  ],
  "paging": {
    "after": "string",
    "nextPageToken": "string",
    "page": 1,
    "pageSize": 1,
    "totalRows": 42,
    "totalPages": 42
  }
}

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 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.

More in Ad Insights

GETGoogle Ads search terms report GETGoogle Local Services Ads leads GETList lead conversations GETGet campaign analytics POSTGenerate keyword ideas POSTGet historical keyword metrics POSTSubmit async insights report GETPoll an async insights report run GETGet ad analytics GETPer-creative performance inside TikTok Smart+ ads