api
Data model
Public evidence about brands' ads and organic posts, in stable snake_case fields.
Updated · API v1
Conventions
- Fields are snake_case and stable within v1. New fields can appear; existing ones keep their name and meaning (see Changelog).
- Times are ISO 8601 in UTC. Ranges: 30d, 90d, 180d or all for reports and post-ad pairs; 30d or 90d for social statistics (each parameter lists its own).
- null means unknown or not public, never zero. A count a platform does not show is null.
- Paid answers carry billing.credits_charged. On Enterprise it is always 0: there is no credit count, your contract covers use.
- Everything is public evidence: ads seen in public libraries, public posts and their public counts. Days active and AI tags are not spend, reach, targeting or results.
Objects
| Object | Identifier | What it is |
|---|---|---|
| Brand | brand_key | An advertiser as Adspy consolidates it across the Meta and Google libraries, with its collected social accounts. |
| Creative | id | One ad creative (image, video or carousel), with its first and last sighting, status, days active, tags, copy and media. Source ads (variants) are the library ads that show it. |
| Creative analysis | id | The creative's AI reading: hook, scores of the execution (not measured performance), objective, timed moments and the full analysis document. |
| Social account | account_id, social:{platform}:{id} | A TikTok or YouTube account. official is true only with proof that it belongs to the brand. |
| Post | id, {platform}:{post id} | An organic post with its public counts, snapshots and AI tags. |
| Post run as ad | pair_id | An organic post and the ad cut from it, or an ad later posted organically, matched by media. |
| X-Ray | brand_key and range | The observed creative strategy: formats, hooks, funnel, longevity, audience estimates, destinations and changes. |
| Social report | brand_key and range | Organic cadence, views and engagement per view with intervals, breakouts and paid reach. |
| Full Analysis | brand_key and range | Ads, organic posts and the links between them, every number with its n, interval and test, multiple-testing corrected. |
| Collection | id | A workspace's saved creatives with their notes. |
| Export | job_id | A file built in the background. |
| Fetch | job_id | A brand or account collection. |
Platforms
Ads come from the Meta Ad Library (Facebook, Instagram and Audience Network placements) and Google Ads Transparency (Search, YouTube, Display). Organic posts come from TikTok and YouTube. Instagram accounts and posts are not available in the API.