ads
POST /v1/ads/analytics/narrative
The selected period in plain words - what moved, why, and where the month is heading - with every figure checked (za-285).
Authentication
Send an API key as a bearer token. The key must carry the ads.view permission; a key without it is refused with 403, not 404.
Where your organisation id goes
This endpoint takes org_id as a field in the JSON body.
Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/ads/analytics/narrative \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Gated on ads.view (none anywhere is a 404, nothing spent); the paying organisation is ONE organisation (org_id in the body, the query or X-Zinn-Org when the caller holds several; two that differ are a 422 orgRequired with detail code mismatch), and the figures are that organisation's and its client organisations' only - the same filters as every analytics read, in the query. Written by Zinn® AI from numbered facts built from the stored figures: the period's totals against the comparison period, the campaigns whose spend moved most, the unusual days with the changes made in the days before them (by Zinn® Ads, by people on the account, by Google), the change counts and, when the period reaches this month, the month-end forecast against the spend ceiling. Every number in text must be a figure of a fact it cites (cites, facts), or the narrative is withheld and never shown. Cached per (organisation, scope, period, data hash): the same view over the same figures is read back (cached: true) and never paid for twice; any changed figure is a new hash, a new narrative, and the old one for that scope and period is retired. A percentage must carry its fact's direction (fell 20% against +20% is withheld), a percent word is a percentage, and no number - not a small count, not a word such as doubled - is shown unless a cited fact holds it. Other languages: ONE batched translation for the reader's locale (normalised to a language we ship, e.g. ar-EG is ar; any other value is answered in English and buys nothing) and the languages the organisation's people read, each re-checked against the same facts the same way (a translation that changed a figure, or added a direction or a number word the English lacks, is dropped and never bought again for that text; a language the check cannot read is never bought and is answered in English; translations take at most half of the hourly brake and are metered under ads_narrative on the PLATFORM's own scope, never the customer's included allowance, and only for an org in good standing); locale in the reply is the language text is in (en until a translation is held). A percentage whose direction cannot be read, or a rise/fall word against a cited money figure's own direction, is withheld. status: empty (no spend in the period or before it; no model is asked), writing (another request is writing it; ask again shortly), written, withheld, refused (no AI credit, or not in good standing - failure class refused, nothing spent) or failed (the AI provider failed - failure names the class; nothing charged; the next view tries again). Who pays is the one meter's decision: the organisation's own AI key, else its Zinn® AI credit; the model is the cheapest verified, priced one. 422 codes: analyticsFilter, narrativeHourly (60 billed calls - writes and translations, failed ones included - per organisation per hour), orgRequired.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
range (query) | string<7d, 30d, 90d, ytd, 12m, custom> | No | The period. custom takes from and to. |
from (query) | string | No | — |
to (query) | string | No | — |
compare (query) | string<previous, year, none> | No | — |
grain (query) | string<day, week, month> | No | Bucket size. Default day up to 92 days, week up to 366, month beyond. |
network (query) | string | No | Comma-separated networks (google, microsoft, meta, linkedin, tiktok, x, pinterest, amazon). |
connection (query) | string | No | Comma-separated ad-account connection ids. |
campaign (query) | string | No | Comma-separated <connection_id>:<campaign_id> tokens. |
country (query) | string | No | Comma-separated ISO 3166-1 alpha-2 codes. Reads the country-level figures. |
device (query) | string | No | Comma-separated devices: mobile, desktop, tablet, tv, other (za-282). Reads the device-level figures (Google Ads accounts, campaign grain). No stored level is split by… |
offering (query) | string | No | Comma-separated product/site ids (za-290), or unassigned. |
client (query) | string | No | za-287: comma-separated client organisation ids. The read narrows to each client and its own clients, so an agency sees the same screen for one client. A client the caller cannot… |
currency (query) | string | No | Reporting currency (ISO 4217). Default the one currency in play, else the organisation's. |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
org_id | string | No | — |
locale | string | No | The reader's language, e.g. en, ar. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
data | AdsAnalyticsNarrative | Yes | za-285: the period narrative. status empty carries only status and cached. text is empty unless status is written. facts are the cited facts (figures as the… |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429