Kreel

Soft-archive a decided experiment. Its result and learning remain available.

archive_experiment

Soft-archive a learning (drops it from the active set and the cap count). Args: brand: Brand name or id. Required when you can reach more than one brand.

archive_learning

Compare a metric across subjects, optionally against a derived period. A single subject is supported when comparison is supplied. Every subject carries `revenue_kind`, matching get_performance's vocabulary: `store_net` (a Shopify account subject — refund-correct NET store revenue, so it reconciles digit-for-digit with get_performance), `platform_attributed` (an ad/email account or any campaign subject — provider-reported value under its own attribution model and click/view windows, not necessarily last-click; equal revenue kinds do not imply equal attribution settings), or `blended` (a platform='all' account subject — store net plus attributed, which are different bases and are not additive). When `metric` is `revenue` or `roas` (both read the same revenue basis) and the subjects mix revenue kinds, a top-level `notices` entry flags that the numbers are not directly comparable. Args: brand: Brand name or id to query. Required when you can reach more than one brand; optional (auto-selected) when you can reach exactly one. Call list_brands to see options. account: Optional Connected Account or list of them (each a display name, platform account id, Kreel id, or a saved Account Group name, which resolves to its member set; several values union) applied to EVERY subject, so subjects stay comparable. Omit it to compare across the blend of all the brand's accounts. An account the brand does not hold returns {"error": "unknown_account", "available_accounts": [...]}. subjects: list of {"label", "platform", "entity_type", "id"?}. entity_type = "account" compares full channels; "campaign" requires an "id" (platform_campaign_id). "email_campaign" and "flow" accept Klaviyo ids, optional account_id and send_channel (email/sms), with platform "klaviyo" or omitted. Rates are unique/delivered fractions. Campaign cohort comparison is group-analysis with source_type=campaign. `subject.platform` is optional and defaults to 'all' (blended across every connected channel). Campaign subjects support 'meta', 'google', 'tiktok', or 'all'; 'all' scans every paid-ad platform. Campaign lookup scans only the top ~1000-by-spend campaigns and matches by id; set the subject's `platform` to avoid cross-platform id collisions, and 'no data' may mean truncated rather than absent. GA4 subjects (platform "ga4", never mixed with other platforms) are the website or one segment: entity_type "website", or "channel_group" | "traffic_source" (source / medium) | "device" | "landing_page" with `id` = that value, plus optional GA4 `filters` (channel_group, source_medium, device_category, landing_page). GA4 metrics: sessions | engaged_sessions | engagement_rate | purchase_session_rate | ecommerce_purchases; each subject lists its GA4 warning codes and a comparison is withheld unless stored GA4 data covers the whole comparison window. comparison: Optional {"mode": "previous" | "year" | "custom", "start"?, "end"?}. Derives period-over-period values with strict coverage. delta_pct is (current - previous) / previous, rounded to 4 places (0.1 means 10%). metric: spend | revenue | roas | cpa | orders | conversions | ctr | delivered | open_rate | click_rate | revenue_per_recipient. For account subjects, `orders` and the denominator of `cpa` use Shopify store orders for Shopify, platform conversions for Meta, Google, and Klaviyo, and the corresponding sum for a blended `all` subject. For campaign subjects, `orders` equals conversions (no true order count exists at campaign level). window: {"days": 7} OR {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"}. `window` defaults to the last 7 days; day-count windows end yesterday, not today. sales_channels: Optional normalized Shopify `source_name` allowlist. This applies to Shopify-derived revenue and orders for account subjects whose platform is "shopify" or "all", and wins over the brand exclusion policy. Ad and email subjects remain unfiltered. A blended account therefore uses filtered store revenue with its full attributed data and full spend. Use "__unknown__" for orders without source_name. Unknown values return an error with observed values. Omit the argument to use the brand policy; [] is invalid.

compare

Flag channel and campaign metric changes with structured evidence. Inventory stockout_risk and dead_stock use canonical products and trailing 28-day velocity. Linked ACTIVE Meta spend is best-effort, Meta only and tagger-dependent; inspect inventory_metadata.advertising_coverage for partial coverage. Klaviyo campaign bounce/spam rates compare with preceding account sends: at least 1,000 deliveries and 5 bounces / 3 complaints, +0.005 / +0.0005 absolute rate increases, and 25% / 50% relative warn / critical increases. Measured zero-baseline spikes are new_activity; flow gaps are omitted. Also detects product/variant high_return_rate against the recent store baseline (30 sold, 5 refunded, 100 store units; +5pp and 2x warn/3x critical). Linked active Meta spend is canonical-product evidence over the last seven completed days, separate from the return window. The tool evaluates spend, revenue, orders, ROAS, CPA, CTR, and CPM. Additive metrics (spend, revenue, orders) are compared as calendar-day averages; ratios (roas, cpa, ctr, cpm) are recomputed from summed bases, never averaged. Each alert's evidence carries ``basis``: ``"daily_avg"`` for the additive metrics or ``"ratio"`` for the ratio metrics, alongside the ``window_value``/``baseline_value`` keys (unchanged). Channel ``orders`` means store orders for Shopify and platform conversions for attributed channels; campaign ``orders`` also means platform conversions. Google values may be fractional. Results are capped at the 10 highest-severity alerts and ``truncated`` says whether more matched. Default warn / critical percent thresholds are: spend 25/50, revenue 20/40, orders 20/40, ROAS 20/40, CPA 25/50, CTR 20/40, and CPM 25/50. Direction is literal ``up`` or ``down``, not a claim that a movement is good or bad. A zero baseline is only flagged for spend at 50 account-currency units per day or orders at 5 per day. It is ``new_activity`` when the recent value crosses that floor and ``stopped`` when a baseline above the floor falls to zero. New activity has null ``pct_change``; stopped activity has -100. Twice the floor is critical. Undefined ratios and other zero-baseline metrics are skipped. Channel revenue is refund-correct store net for Shopify and platform-attributed value elsewhere. Campaign revenue is platform-attributed. Attribution models and click/view windows differ by provider; the `platform_attributed` label does not imply last-click attribution. Revenue and ROAS evidence carries ``revenue_kind``. Campaign evaluation is bounded to the top 20 by baseline spend, plus bounded current-only launches. Args: metrics: Optional metric allowlist, including days_of_cover and velocity. brand: Brand name or id to query. Required when more than one brand is reachable; optional when exactly one is reachable. Call list_brands to see options. account: Optional Connected Account or list of them (each a display name, platform account id, Kreel id, or a saved Account Group name, which resolves to its member set; several values union). Omit it to detect anomalies over the blend of every account; name one to detect them within that account alone, which is how a swing in one market stops being averaged away by the others. A brand with several accounts on one platform gets an `accounts` manifest naming what was folded in. An account the brand does not hold returns {"error": "unknown_account", "available_accounts": [...]}. window: Recent period, default {"days": 7}. baseline_window: Comparison period. Defaults to the 14 days immediately before ``window``. threshold: Optional backwards-compatible extra minimum percent change. It can make detection stricter but cannot lower the metric table. channels: Exact channel ids to include: meta_ads, google_ads, tiktok_ads, klaviyo_email, klaviyo_sms, or shopify_store. Any unrecognized id - alone or mixed with valid ones - returns a structured error {"error": ..., "valid_channels": [...]} instead of a silently filtered or unfiltered result. severity: Optional subset of "critical"/"warn" to include. Applied before the top-10 cap, so a window with more than 10 critical alerts no longer starves out every warning - call again with severity=["warn"] to retrieve them. Omitted (default) keeps all severities. An empty list is a structured error - severity must be a non-empty subset when provided, or omitted entirely to get all severities. An unrecognized value returns a structured error {"error": ..., "valid_severities": [...]}.

detect_anomalies

Return a deterministic, source-cited seven-day growth brief. Inventory includes the top three stockout risks, dead stock and coverage counts. Current catalog stock uses velocity ending at the brief end, capped at yesterday; advertising is partial, Meta only and tagger-dependent. Args: brand: Brand name or id to query. Required when the caller can reach more than one Brand. week_ending: Optional YYYY-MM-DD final day. It must be before today. Omit it for the last seven complete reporting-calendar days. Includes experiments due for review and verdicts landed in the window, with source links to the immutable ledger. Reads never trigger review. Includes creative_fatigue: independent Meta alerts, all-ad counts and daily spend, up to ten examples and resolvable source citations. Diagnostic windows end no later than yesterday; missing data is disclosed. The response includes refund-correct store revenue, refunds, paid spend, MER, paid-platform ROAS, CAC based on Shopify first orders, Klaviyo attributed revenue, campaign movers, threshold anomalies, fixed-rule next actions, and a citation for every source. Store and attributed revenue are different bases and must not be added.

get_weekly_growth_brief

Return identity, operational metadata, and the saved brand profile. Top-level fields: id, name, currency, timezone, revenue_basis, `sales_channels`, is_active, onboarded, and `connections` (each connected platform with account name, active flag, and whether it last errored) — the context needed to interpret figures correctly (currency on revenue, timezone on date boundaries, which platforms have data). `timezone` is the resolved reporting timezone (the Shopify shop's own timezone while Shopify is connected, else the brand profile's saved timezone, else UTC) - the same value `readiness.expected_data_through` and every daily table's day boundaries are computed from. It is not the raw, unbackfilled profile setting. `connections` includes only currently-active platforms; disconnected ones are omitted (not shown with is_active=false), so per-connection `is_active` is always true. `account_groups` lists the Brand's saved Account Groups — named cross-platform sets of Connected Accounts ("EU", "US") — as {name, id, member_count, platforms}. A group name is a valid `account` argument on every read tool and resolves to its member set; the result's accounts manifest then names the group. Empty when the brand has none. Each connection carries freshness signals: `data_through` is the latest activity date represented in queryable rows, `materialized_at` is when those query rows were last rebuilt, `materialized_from` and `materialized_through` identify the rebuilt date window, and `last_synced_at` is when the last completed performance-relevant Sync Run finished. These can differ when a sync and materialization find no newer activity. `data_through` is measured from a single representative channel per platform (Shopify = shopify_store), not every channel that platform may feed. `last_sync_status` is the latest performance-relevant Sync Run's status, including failures. `last_sync_partial` is true when that run completed but recorded slice errors. `materialized_at` advances after a successful full materialization pass even when sparse activity produces no query rows. `readiness` is the mandatory preflight for performance analysis. Call this tool before `get_performance`, then disclose every warning before interpreting rows. `ready` is false when there are no connections or a connection has missing data, source data not synced or query data not materialized within `freshness_target_hours`, the materialized window does not cover the documented 30-day analysis range, a failed or partial latest sync, or a connection error. Sparse platform activity is not considered stale when both the source sync and query surface refresh are within the freshness target. `expected_data_through` is yesterday in the Brand's reporting timezone. Machine-readable warning codes are `no_connections`, `missing_data`, `stale_data`, `sync_failed`, `sync_partial`, and `connection_error`. `data_coverage` reports the queryable historical window at reporting-table, platform, and day/month grain. `observed_periods`, `span_periods`, and `has_period_gaps` distinguish a continuous period range from sparse history. Applicable connected-platform slices with no rows are explicit `no_data`. `completeness` is always `unknown` and never promoted to `incomplete` or `complete`: row-date gaps are activity gaps, not provably ingestion gaps (materializers only write rows for periods that had activity, so a legitimately quiet day produces the same gap shape as a failed sync), and a gap-free range does not prove every expected entity or monetary row was ingested either. A trustworthy completeness verdict would need the durable sync/materialization coverage ledger, not row presence - that is out of scope for this field. Use `has_period_gaps` to judge sparseness, but never read `completeness` as a completeness guarantee in either direction. `sales_channels.policy` is the brand's persisted exclusion list. Newly discovered Shopify channels are included by default. `sales_channels.available` lists observed normalized Shopify source_name values with labels and all-time order counts. Pass one or more of those `channel` identifiers to the `sales_channels` argument on get_performance account/product queries or compare for a per-call allowlist override. The reserved "__unknown__" identifier selects orders without source_name. Ad-platform and email metrics are never filtered by this Shopify policy. Brand Knowledge Base — anchor every recommendation in this: - `context`: the Brand Profile typed anchors — vertical, price_tier (value/mid/premium/luxury), margin_band (lean/moderate/healthy), target_roas, target_cpa, target_aov. Individual fields may be null; check before use. - `sections`: prose markdown documents keyed by `key` (positioning, icp, competitive_landscape, brand_voice) — the brand's narrative and voice. - `competitors`: the brand's named rivals (name, handle, differentiator). - `learnings`: durable insights (id, topic, content, evidence) the brand has accumulated across sessions. `learning_cap` is `{active, cap}`. `is_empty` is true when the profile, sections, competitors and learnings are all unset — point the user at onboarding (the `/onboard-brand` skill). Args: brand: Brand name or id to query. Required when you can reach more than one brand; optional (auto-selected) when you can reach exactly one. Call list_brands to see options.

get_brand_context

Fetch creative performance for Meta ads, TikTok ads or Google assets. Meta-only naming: `naming` contains strictly parsed, case-sensitive values (UGC and ugc differ), or null. Configured fields support filters/group_by; missing values form an `unmatched` bucket. `naming_matched` filters coverage. `rank_by` ranks rollups by a chosen metric; `min_spend` sets a Base-currency spend floor. Incomplete/undefined groups are excluded and counted; cost metrics rank ascending, other metrics descending. `limit` caps ranked groups. Google has no naming schema, filters, or group_by support. This is the tool for creative analysis: each creative carries its delivery **performance over a window** (spend/impressions/roas/ctr/cpa…) plus fatigue diagnostics and Kreel's AI creative tags, so you can answer "which hooks/formats convert" and "what's fatiguing" in one call without joining tables yourself. ⚠️ **Media URLs and ad copy require `fields="all"`.** The default `fields="core"` is token-safe and returns NO media/copy and NO Gemini prose — see `fields` below. Canonical Meta hook_rate = thumbstop = video_3_sec_views / impressions; thruplay_hold_rate = thruplays / video_3_sec_views (15 seconds or completion). These are four-decimal fractions, null for missing inputs or nonpositive denominators. Asset grouping uses confirmed image hashes only, falling back to account-scoped creative identity, then ad identity. Legacy fatigue uses 30-second video_views for hook and p100 / video_views for hold. **Google v1 is metrics-only at asset + field-type grain.** It covers RSA and Demand Gen assets through `ad_group_ad_asset_view`, and PMax assets through `asset_group_asset`. Rows include asset id, type, name/text when Google supplies it, field_type, performance_label, impressions, clicks, ctr, conversions, conversion_value, and cost. The envelope and each row echo the selected Google customer id so asset identities stay account-scoped. Google v1 has no Gemini tags, media URLs, fatigue, filters, or group_by. Pass `fields="core"`; `tags` and `all` return an explicit not-available error rather than silently degrading. When the Google page comes back empty, the envelope adds an `empty_reason` so a zero result is never ambiguous: "asset_metrics_not_synced" (the per-asset sync has never populated this account - no rows for the selected customer on any date, e.g. the pipeline hasn't run or a shared-quota hit kept coming up empty) vs "no_rows_in_window" (rows exist for the account, just none delivered in the requested window - widen `date_range`). **TikTok is ad-grain creative parity with Meta** (#642 D4): each delivered TikTok ad that has a fetchable asset is one row carrying `creative_id` (its video_id, else first image_id - reuse across ads shares one id and one stored copy), `asset_kind`, `media_type`, the shared `hook_type` / `format_type` tags, `intelligence` (`fields="tags"`), Kreel-signed `image_url` / `video_url` plus `body` / `call_to_action` / `landing_page_url` (`fields="all"`), and spend / impressions / clicks / `purchases` (website purchases) / `revenue` (their TikTok-attributed value) / `cta_conversions` / `vta_conversions` with derived roas / cpa / ctr / cpm / cpc / conversion_rate and a per-row `attribution` block, exactly as `get_performance(platform= "tiktok", entity_type="ad")` reports them; a `semantics` block restates the definitions. Delivered ads with NO fetchable asset (Spark Ads without a video_id, LIVE_CONTENT, CATALOG_CAROUSEL) are excluded from the rows and counted, with their spend, in `without_creative` - `total_creative_spend` covers only the rows a creative ranking can see. Filters: ad_id, campaign_id, adset_id (= adgroup_id), status (the raw TikTok operation_status switch, e.g. "ENABLE" - advertiser-enabled, NOT guaranteed delivery). Each row carries both `status` (that switch) and `secondary_status` (TikTok's effective delivery state, as `get_entities` reports it): an ENABLE ad under a paused campaign / ad group reads status "ENABLE", secondary_status "AD_STATUS_CAMPAIGN_DISABLE" / "AD_STATUS_ADGROUP_DISABLE" and lifecycle_stage "paused" - lifecycle is judged on the effective state. group_by: hook_type, format_type, media_type (rollups carry the same measures; `rank_by` accepts roas / cpa / ctr / cpm / cpc / conversion_rate / spend / revenue / purchases). `lifecycle_stage` / `lifecycle_reason` / `lifecycle_bar` / `lifecycle_bar_source` come from the Brand's TikTok stage-rule row (per-platform, #466) over the same fixed 30-day window as Meta's; the Meta-only `fatigue` block is absent, not null. Do not compare raw TikTok and Meta ROAS: the platforms attribute differently. **Window-scoped & delivered-only:** results are driven by delivery in `date_range` (default last 7 days) — a creative that didn't spend in the window is not returned. To browse the whole active library, pass a wide window (e.g. `{"days": 365}`). Metrics match `get_performance(entity_type="ad")` digit-for-digit for the same window. **Two shapes:** - per-creative (default): one row per creative, spend desc. - rollup (`group_by` set): blended performance per `hook_type`/`format_type`/`asset` — ratios recomputed from summed base measures (never averaged), with a `creative_count` and an `untagged` bucket so spend reconciles. Returned under a `groups` key; media/copy/`fields`/fatigue are not applicable. Separate from get_entities because creative responses are token-heavy (media URLs + copy bodies) and have per-asset metadata. Each creative returns (in every `fields` tier from `core` up): - spend / impressions / clicks / reach / purchases / revenue and derived roas / cpa / ctr / cpm / cpc / conversion_rate over `date_range` (each ratio omitted when its denominator is 0). Creative revenue/roas/purchases are Meta-attributed (platform-reported, attribution-window dependent), not Shopify-verified store revenue. - mid-funnel counts add_to_cart / initiate_checkout (their `*_value` totals only when nonzero) — check ATCs before killing a zero-purchase ad. Meta-attributed, like purchases. leads / lead_value appear only when nonzero (most brands run none). - the video funnel, when the creative is a video (per its metadata) or the window saw video delivery: video_views (Meta 30-second views, not 3-second) + video_views_p25/p50/p75/p95/p100 percentile completions. NOTE the two use DIFFERENT measurement bases: video_views counts plays reaching 30 continuous seconds (an absolute time threshold - or the full length for videos shorter than 30s), while video_views_pXX count plays reaching XX% of the video's OWN length (a relative threshold, no 30-second floor). For a sub-30s creative - most short-form paid video - clearing 95% of a short clip is a lower bar than 30 continuous seconds, so video_views_pXX routinely EXCEEDS video_views. That is expected Meta reporting for short video, not a data defect. A delivered video nobody watched shows measured zeros; static creatives omit the group entirely - a structural gap, not a measured 0. These also blend per group in rollup mode. - creative_id — the Meta creative behind the ad. The same asset reused across ads/geos shares one creative_id, so join duplicates on it instead of matching ad names. Null until structure sync captures it. - first_delivery / age_days — first delivered date over the full synced history (not `date_range`) and days since, for launch-cohort reads. - landing_page_views / video_3_sec_views / thruplays / video_avg_watch_time_sec (unweighted mean of per-day averages; per-creative rows only, not rollups) — the counts appear only when EVERY contributing row in the window carries them (synced after the KRE-279 extension); a window crossing the rollout boundary omits them instead of publishing a partial total. Absence means not fully synced (re-sync history to fill), never a measured 0. video_3_sec_views/impressions is the classic hook rate; the fatigue block's hook_rate stays video_views (30-sec) based. - quality_ranking / engagement_rate_ranking / conversion_rate_ranking — Meta's diagnostic rankings; per field, the latest value reported in the window. A key is absent when Meta never reported that field (below ~500 impressions or unsynced). - hook_type — AI-classified hook (e.g. problem_solution, testimonial, product_demo, fomo_urgency). - format_type — AI-classified format (e.g. static_image, carousel, video_ugc, video_branded). - lifecycle_stage — testing / scaling / winner / fatiguing / kill / paused / dormant, from a fixed trailing 30-day window — deliberately a *different* window than `date_range`, so a creative can be a 30-day `winner` while showing 0 spend in a narrower `date_range` (a fatigue signal, not a contradiction). The five PERFORMANCE stages are defined by the brand's editable per-Brand stage rules in fixed precedence (Kill > Fatiguing > Scaling > Winner > Testing, first match wins; Testing is the residual), judged against a per-audience-temperature efficiency bar (cold/warm/retargeting each default to their own cohort's blended ROAS, overridable with an explicit target; unclassified/other temperatures use the account blended bar), so a performance stage is relative, not an absolute quality signal. Two values are NOT performance stages (ADR-0016): "paused" — the ad's effective status is not ACTIVE (a paused parent ad set/campaign pauses the ad: Meta's effective_status, TikTok's secondary_status); it is a status, never a stage, and "kill" is reserved for LIVE ads failing the kill rule. "dormant" — the ad delivered inside `date_range` but has no row in the trailing 30-day window (it ran and stopped); it is NOT kill. Always set (results are delivered-only, so "never delivered" can't occur). "kill" replaces the retired "dead". - lifecycle_bar / lifecycle_bar_source — the exact efficiency bar this creative's stage was judged against and where it came from ("cohort_default" | "explicit_target" | "account_fallback"), so an agent reads the same bar the dashboard board prints. Both null for a "dormant" creative (outside the classification window, no bar resolved). - lifecycle_reason - WHY a `kill` creative is kill; null for every other stage (including "paused" and "dormant", which are self-describing: a Meta row's `status` and a TikTok row's `secondary_status` show the non-active delivery state behind "paused"). Kill has ONE meaning now: "underperforming" — still ACTIVE and delivering, but its recent AND cumulative ROAS are both below the brand's kill% of the efficiency bar (a deliberate "should be killed" verdict, NOT a delivery-state fact). An "underperforming" creative may still be actively spending. Also null on a `kill` creative whose ad metadata is missing (performance rows survive a deleted Meta ad row) - status is unknown there, so it is classified purely on performance, never assumed paused. - fatigue.alert — independent deterministic per-ad rule in every field tier: CPC rises >=25% AND measured three-second hook rate or ROAS falls >=20%, subject to current brand fatigue_alert_* settings and both-window floors. Compares seven days ending at requested end (capped at yesterday) with prior seven; echoes both windows, coverage, thresholds and inputs. Distinct from lifecycle stages and legacy descriptive trends. Frequency is contextual only. - fatigue — diagnostics over `date_range`: window scalars hook_rate (video_views/impressions), hold_rate (video_views_p100/video_views), ctr; for non-video creatives (no video_views) hold_rate is null - not-applicable, not missing data - while hook_rate reads a real 0; and `trend` (first-half vs second-half) for ctr/hook_rate/frequency, each {first_half, second_half, delta_pct}. `trend` is null when the window has < 2 days/side. NOTE: frequency is trend-only — there is no cumulative window frequency scalar, by design (reach is unique users and doesn't sum across days, so Σimpressions/Σreach would be wrong — ADR-0007). With `fields="tags"` each creative additionally carries `intelligence` — Gemini per-creative analysis: description, hook_summary (the literal opening hook), angle (the persuasion strategy), first_3_seconds, spoken_or_onscreen_text, pacing. With `fields="all"` it additionally carries image_url / video_url / headline / body / call_to_action — the asset and copy. `image_url` / `video_url` come in two forms, and only one is durable at publish: - **Kreel signed URL** (`…/storage/v1/object/sign/creative-assets/…`) — returned when the own-the-asset pipeline has stored the media (KRE-151). This is the **durable-at-publish source `publish_report` freezes**: reference it directly in report HTML and `publish_report` snapshots it into the report and serves it permanently, so its ~1-hour signing only needs to hold at publish time. - **Meta CDN URL** (a `…fbcdn.net…` / non-Kreel link) — the fallback returned when Kreel has not stored that creative's media yet. `publish_report` does NOT snapshot it, so it will expire and 404 in the frozen report. Check the URL form before relying on it; when it is a Meta CDN link the asset isn't yet freezable (re-sync/backfill the creative, or omit it). Either way, do NOT base64-inline the media. Use `image_url` / `video_url` as the durable source - the raw `creatives` table (via the `query` DSL) does not carry a public image/video URL at all. hook_type / format_type / intelligence are null until the Gemini tagger has analyzed the creative. For raw column-level access to the analysis across all creatives, the `query` DSL exposes the `creative_intelligence` table. Args: brand: Brand name or id to query. Required when you can reach more than one brand; optional (auto-selected) when you can reach exactly one. Call list_brands to see options. account: Optional Connected Account or list of them (each a display name, platform account id, Kreel id, or a saved Account Group name, which resolves to its member set; several values union) to narrow the creatives to. Omit it to read every account the brand holds; a brand with several accounts on one platform then gets an `accounts` manifest naming what was folded in. For Google, a named account overrides the credential's selected customer. An account the brand does not hold returns {"error": "unknown_account", "available_accounts": [...]}. platform: "meta", "tiktok" or "google". Google is metrics-only in v1; TikTok is ad-grain creative parity (see above). filters: Meta only: {"ad_id": "...", "campaign_id": "...", "adset_id": "...", "status": "ACTIVE"}. ad_id is the Meta ad id. Unknown keys are rejected. Apply in every mode, including rollup (e.g. hook breakdown within a campaign). Google v1 rejects filters explicitly. group_by: Meta supports ["hook_type", "format_type", "asset"] and configured naming-schema fields. TikTok supports ["hook_type", "format_type", "media_type"]. Dimensions can be combined per platform. When set, returns blended performance per group under `groups` instead of per-creative rows. Other keys are rejected. Google v1 rejects group_by. rank_by: Meta or TikTok rollup metric to rank by, e.g. "roas" or "cpa". Requires group_by; incomplete and undefined buckets are excluded. min_spend: Non-negative Base-currency spend floor for ranked groups. Requires group_by and rank_by; defaults to zero. date_range: {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"} OR {"days": N}. Default last 7 days ending yesterday. Scopes both delivery (inclusion) and the attached metrics. fields: one of "core" | "tags" | "all", escalating by real payload weight (default "core"): - "core" (default, lightweight): identity (id/name/adset_id/campaign_id/ status) + tag LABELS (hook_type/format_type/lifecycle_stage) + numeric metrics + the fatigue block. NO Gemini prose, NO media URLs, NO copy. - "tags": "core" + the `intelligence` prose block (6 Gemini fields). - "all": "tags" + media URLs (image_url/video_url) + copy (headline/body/ call_to_action). ⚠️ Media and copy appear ONLY in "all". Google v1 supports only "core" and returns an explicit error for the Meta-specific "tags" and "all" tiers. limit: Max per-creative rows (default 200, hard ceiling 1000 — a token-safety backstop on the heavy fields="all" path). Caps ranked rollups; ignored for unranked rollups. The response also carries a `coverage` block over the returned creatives — {returned, tagged, untagged, with_media} — so you can tell when tag-based cuts are thin (the Gemini tagger may not have processed every creative yet). In per-creative mode `coverage.tagged` counts creatives with a hook/format tag OR Gemini intelligence (independently nullable), so it can overstate `hook_type`/`format_type` label coverage specifically. The counts cover the returned page (capped by `limit`), not the whole library. `truncated` is true when the page filled to `applied_limit` (more delivered creatives may exist below the spend-desc cut — widen `date_range` or raise `limit`). Truncation ties out: `total_creative_spend` is the spend of ALL delivered creatives matching the filter (no limit), and `omitted` = {count, spend} is what falls below the cut, so Σ(returned spend) + omitted.spend == total_creative_spend (both zero when not truncated). `total_creative_spend` reconciles the page to its own creative-delivered universe; it may still differ slightly from account-level Meta spend (ads with no creative record, deleted ads). Google responses use the same pagination reconciliation shape with `count`, `applied_limit`, `truncated`, `total_creative_cost`, and omitted count/cost. Their `coverage` block is {returned, total, truncated}; tag/media coverage does not apply to the metrics-only Google v1 surface.

get_creatives

Cross-brand performance summary for every brand you can reach, in one call. Built for the agency workflow — "what changed across my clients this week, who needs attention?" — without an agent making N sequential get_performance calls. There is no `brand` argument: like `list_brands`, this operates on your ENTIRE reach (`CallerReach.accessible_client_ids`), never a single selected brand. Rows are grouped under `workspaces`. A Supabase user who belongs to more than one workspace gets one group per workspace; an API key reaches exactly one workspace, so it always yields a single group. Each group carries `workspace_id`, `workspace_name`, `total_brands` (every brand you can reach in that workspace, before `limit` truncates the list), and `brands` (up to `limit`, SORTED WITHIN THIS GROUP by `sort_by` — never across groups). Each brand row: - `id`, `name`: pass `id` as the `brand` argument to get_performance, compare, or get_brand_context to drill into that brand. - `currency`: the currency the figures are reported in — the Shopify-reported account currency when available (the same one the revenue module resolves), falling back to the brand's configured base currency. There is no FX conversion — a raw `revenue`/`ad_spend` comparison across brands with different currencies is comparing different units. - `revenue`: refund-correct store-net revenue for `date_range` (the exact Period Revenue basis as get_performance's Shopify `revenue_kind= "store_net"` — reconciles digit-for-digit with get_performance for the same brand/window). `revenue_kind` is always `"store_net"` here; platform-attributed revenue appears only inside `platforms`. - `orders`, `aov`: the same refund-correct Shopify order count backing `revenue`, and net revenue / orders — `aov` is null when orders is 0. - `ad_spend`: Meta + Google spend from `daily_channel_summary` for the window (email/organic carry no ad spend). - `mer`: store-net revenue / ad_spend (blended marketing efficiency, the same ratio get_performance's account-level summary reports) - null when ad_spend is 0, never a division error. - `platforms` (present only when the brand has ad/email rows in the window): per-platform "most important metrics" rollup. `meta` and `google` share the same base metric set - `spend`, `attributed_revenue`, `roas`, `cpm`, `conversions` (fractional, KRE-200) - so blended `cpa` (spend / conversions) is derivable per platform; `meta` additionally carries `ctr` (0-1 fraction) and `cpa`, `google` additionally carries `cpc`. `email` carries `attributed_revenue`, `revenue_share` (email attributed revenue / store-net revenue), `open_rate`, `click_rate` (unique engagement over delivered, 0-1 fractions). All platform revenue is PLATFORM-attributed - a different lens than the store-net `revenue`/`mer` above. Every division is null when its denominator is 0, and a platform with no rows in the window is omitted, never zeroed - a structural gap must not read as a measured 0. - `connected_platforms`: count of the brand's currently active platform connections. - `data_through`: the OLDEST per-platform freshness date among the brand's connected platforms (the same freshness get_brand_context reports per connection) - so one stale connection makes the whole brand read as stale even if its other platforms are current. A connected platform with NO queryable data yet nulls `data_through` entirely (it never silently drops out of the minimum); when that happens, `platforms_missing_data` (present only when > 0) counts the connected platforms with no data. `data_through` is also null when the brand has no connections at all (`connected_platforms` is 0 and `platforms_missing_data` is absent). Call `get_brand_context` on a brand flagged stale here before trusting its numbers. - `comparison` (present only when `compare_to_previous=True`): the ADR-0010 comparison block versus the equal-length immediately preceding window - `mode`, `start_date`, `end_date`, plus `metrics` (the SAME shape as the row's own figures, computed over the comparison window). Coverage is per SECTION: a section whose source history does not span the window (base Shopify figures / blended ads / each platform) is absent from `metrics` and named in `coverage_gaps` with a machine-readable reason - never a delta against partial sums. `reason` replaces `metrics` only when no section at all is comparable. - `vs_previous` (present only when `compare_to_previous=True` AND the comparison has `metrics`): the KRE-174 back-compat delta trio `revenue_delta_pct`, `spend_delta_pct`, `mer_delta_pct`, derived from `comparison.metrics`. Each is null when its prior-period denominator is 0 or undefined, per the shared KRE-128 delta convention. A workspace group also carries an optional `subtotal` (currency, revenue, ad_spend, orders, mer) ONLY when every brand reachable in that workspace shares BOTH the same base currency AND the same resolved revenue policy (Revenue Basis - tax/shipping inclusion - and excluded sales channels); otherwise it is omitted, never approximated - two same-currency brands whose revenue is computed under different definitions are just as non-summable as two currencies. There is deliberately NO cross-brand total anywhere else in the response — brands can report in different base currencies, timezones, and revenue policies, so summing them would misstate the portfolio. `notices` always states this explicitly. Args: date_range: Rolling window as a day-count string, e.g. "7d" (default), "30d", "90d" — the same convention as the `kreel` CLI's `--period`. Ends yesterday, like every rolling window in Kreel. sort_by: "revenue" | "spend" | "mer" | "revenue_delta". "revenue", "spend", and "mer" sort each workspace group's brands DESCENDING (largest first). "revenue_delta" sorts ASCENDING (biggest decline first) so the brands needing attention surface at the top of their group; it requires `compare_to_previous=True` and is rejected otherwise. A brand with an undefined value for the chosen key (e.g. `mer` when `ad_spend` is 0, or a "new this period" `revenue_delta`) always sorts last within its group. limit: Max brands returned PER WORKSPACE GROUP (default 25). Capped at 50 regardless of the value passed - this tool runs several queries per brand, so a very large portfolio is capped for latency. Brands beyond the limit are dropped from `brands` but still counted in that group's `total_brands`. compare_to_previous: When True (the default - the OPPOSITE default of get_performance/compare), attach each row's `vs_previous` block. Set False for a faster call when you don't need period-over-period deltas. Results reflect data that has already been synced/materialized - a brand's `data_through` (and `connected_platforms`) tell you how current its figures are; call `get_brand_context` on any brand you plan to act on before trusting its numbers.

get_portfolio

Normalized performance query across connected platforms. Dimension vocabulary (ADR-0024): account rows use `channel` with values meta_ads, google_ads, tiktok_ads, klaviyo_email, klaviyo_sms, shopify_store. Unified ad campaign rows use `platform` with meta/google/tiktok. The `platform` argument selects an integration (also shopify/klaviyo/all); it is not a channel value or a Connected Account id. Shopify sales_channels are separate order sources. Args: brand: Brand name or id to query. Required when you can reach more than one brand; optional (auto-selected) when you can reach exactly one. Call list_brands to see options. account: Optional Connected Account, or list of them, to narrow the read to — each a display name, platform account id, Kreel id, or a saved Account Group name (a Brand-level named set of accounts; see `account_groups` in get_brand_context), which resolves to its member set; several values union into one set. Omit it (the default) to read the blend of every account the brand holds, which is what a brand with one account per platform has always got. A brand with several accounts on one platform gets an `accounts` manifest naming what was folded in, and any read narrowed with this argument carries the same manifest; when the selection is exactly one group, the manifest names it as `group`. An empty group reads as zero rows with `count: 0` — the group exists but has no readable members. Naming an account the brand does not hold returns {"error": "unknown_account", "available_accounts": [...]} (plus `available_groups` when the brand has groups) rather than an empty result that looks like "no data". platform: "all" | "meta" | "google" | "tiktok" | "klaviyo" | "shopify" | "ga4". "ga4" reads Google Analytics 4 website behavior for the brand's one selected property and web stream, a measurement source kept apart from Shopify commerce and ad-platform attribution. Its entity types: "account"/"website" (sessions, engaged_sessions, engagement_rate, purchase_sessions, purchase_session_rate, ecommerce_purchases, plus ga4_purchase_revenue in the property currency, never to be added to Shopify or ad revenue), "traffic_source" (session source / medium), "channel_group" (GA4 default channel group, paid and unpaid), "campaign" (GA4 session campaign id/name), "landing_page", "device", and "shopping_activity" (observed view_item / add_to_cart / begin_checkout / purchase counts - not a funnel). GA4 filters: channel_group, source_medium, device_category, landing_page (landing pages), campaign_id / campaign_name (traffic); an incompatible filter returns {"error": "incompatible_filter", "compatible_filters": [...]}. filters may also carry min_sessions (int) and, for landing_page, group_by ("device_category" | "channel_group" | "source_medium") to compare pages within one device or source. purchase_session_rate is GA4 sessionKeyEventRate:purchase recomputed from summed purchase sessions / sessions; null means the property has no purchase key event (see meta.warnings), not zero. Every GA4 result carries `meta`: status (ok | empty | partial | syncing | no_coverage | needs_selection | not_connected | permission_lost), the property / stream, exact windows, property vs brand time zone, currency, last_synced_at, coverage, quality (thresholding, (other) rows, sampling, provisional days) and warnings - disclose them. Rows are sessions-descending; `total_rows`/`truncated` say what `limit` cut. sales_channels does not apply to GA4. entity_type: "account" | "campaign" | "adset" | "ad" | "flow" | "email_campaign" | "search_term" | "keyword" | "product" | "product_group" | "asset_group". "adset"/"ad" support Meta Ads, Google Ads and TikTok Ads (platform="google" reads AdSetPerformance/GoogleAdPerformanceDaily; for Google and TikTok, "adset" is an ad-group alias — ad-group discovery is via get_performance(entity_type="adset", platform="google"|"tiktok"), or get_entities(platform="tiktok", entity_type="adset")). For "adset"/"ad", `platform` must be "meta", "google" or "tiktok"; platform="all" returns Meta ads only (Google and TikTok ads are NOT merged in) - query each platform separately to get its rows. Campaign rows carry `objective` — the raw platform objective / campaign type (Meta OUTCOME_SALES/OUTCOME_TRAFFIC/..., Google SEARCH/SHOPPING/ PERFORMANCE_MAX/..., TikTok WEB_CONVERSIONS/PRODUCT_SALES/SHOP/...) — so non-sales campaigns (Sampling/Awareness) read in context; it is omitted when unknown. TikTok ad/adset rows report `purchases` = TikTok website purchases (complete_payment) and `revenue` = their TikTok-attributed value, plus `cta_conversions` / `vta_conversions` — optimization-goal conversions by click-through / view-through attribution that are NOT purchases and are omitted when TikTok reported them unavailable. Every TikTok row carries an `attribution` block (click / view / engaged_view windows and event_count) exactly as TikTok reports it for the ad group; null means not reported, never inferred. The response's `semantics` block restates these definitions. `conversions` on TikTok campaign rows and the `tiktok_ads` account row are the same website purchases. "search_term" and "keyword" are Google Ads only; TikTok has no equivalent, and TikTok creative assets are available through get_creatives(platform="tiktok"). "product" returns Shopify product sales with product title, units, and refund-correct net merchandise revenue in one row. It honors the brand's Revenue Basis and sales-channel policy. Shipping is excluded because it cannot be allocated defensibly to products. Products that were sold but later deleted from the catalog use "Deleted product" as the title so their sales and refunds remain visible. "product_group" returns Shopping product performance (Google Ads only). "asset_group" returns PMax asset-group performance (Google Ads only); note that Google does not expose per-asset metrics — labels only, so metrics here are group-level aggregates. Account rows (entity_type="account") carry `revenue_kind`: "store_net" for the Shopify channel (refund-corrected NET revenue, not the stored gross) and "platform_attributed" for every ad/email channel. Attribution models and click/view windows are provider-specific, not necessarily last-click and not directly comparable across platforms. Do NOT sum `revenue` across channels - the bases differ (store cash-flow vs overlapping platform attribution). Shopify account rows also expose `gross_revenue` and `refund_adjustment`. When platform="all" and entity_type="account", a `summary` block adds blended `mer` = store-net revenue / total paid ad spend (a top-line efficiency ratio, not an attribution model); its `total_ad_spend` covers the whole window regardless of `limit`. The same block also adds `aov` = store-net revenue / orders, and `blended_paid_roas` = summed ad-channel attributed revenue / total paid ad spend (an attribution-based complement to `mer`, not a replacement for it). Both `aov` and `blended_paid_roas` are omitted (key absent, not null) when their denominator is 0 - matching the roas/cpa omission convention used elsewhere in this tool's account/campaign rows. `roas` convention (account/campaign/adset/ad rows): the key is present only when spend > 0 - a real 0.0 when spend > 0 and revenue = 0, and absent (not null) when spend = 0, since ROAS is undefined with no spend. `cpa` follows the same spend > 0 (and, where applicable, count > 0) presence rule. This omission shape is deliberate and by design, not a gap: do not treat a missing `roas`/`cpa` key as 0. date_range: {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"} OR {"days": 7}. Default is the last 7 days ending yesterday. filters: Optional entity filters. For Meta and TikTok ad/adset performance: {"campaign_id": "...", "campaign_name": "...", "adset_id": "...", "ad_id": "...", "name_contains": "..."} (TikTok also accepts "adgroup_id" as a synonym of "adset_id"). Klaviyo email_campaign/flow queries accept {"send_channel": "email" | "sms"}. Other filters on other entity types are ignored. `name_contains` is a case-insensitive substring match against the campaign, adset, and ad names (a row matches on any of the three). metrics: Optional output column narrowing. When given, each row keeps its identity/dimension keys (id, name, channel, campaign_id, status, ...) plus only the listed metrics (e.g. ["spend", "roas"]); requested names absent from every row (unknown, or not produced by this entity_type) are echoed back in `ignored_metrics`. An empty list narrows to identity-only; omit the arg entirely to return all standard metrics. limit: Max rows to return (default 50). Rows are the top `limit` entities ranked by spend (or by revenue/cost, depending on entity_type), descending; lower-ranked rows are dropped silently with no more-rows indicator - raise `limit` for completeness. compare_to_previous: When True, attach a per-row `vs_previous` block (and one on the MER `summary`) comparing each row to the equal-length prior window, and a top-level `comparison_period: {"start", "end"}` disclosing the resolved prior window's dates (same shape as `period`). Supported for entity_type "account", "campaign", and "product" only; ignored otherwise (no `comparison_period` is attached). Product matching uses the current top rows' product ids, so a lower prior rank cannot erase its baseline. `vs_previous.previous` is the prior row's metrics (or null = "new this period"); `vs_previous.delta_pct` is (current − previous) / previous per metric (null when previous is 0). Off by default to keep responses compact. sales_channels: Optional Shopify `source_name` allowlist, for example ["web", "pos"]. This override applies to Shopify-derived revenue and orders on account and product queries where platform is "shopify" or "all". It wins over the brand exclusion policy. Ad-platform and Klaviyo values remain unfiltered, so blended MER uses filtered store revenue over full paid-ad spend. Values are normalized to lowercase; use "__unknown__" for orders without source_name. Unknown values return an error with the observed values instead of being ignored. Omit the argument to use the brand policy. An empty list is invalid. Notes: - Derived ratios (roas, cpa, ctr, cpc, cpm, conversion_rate, open_rate, click_rate, bounce_rate, unsubscribe_rate, spam_rate, revenue_per_recipient) are OMITTED from a row when their denominator is 0 (undefined), not returned as 0. - All rate metrics are 0-1 fractions (never 0-100 percentages), matching the query tool and REST. `conversion_rate` denominators differ by entity: email rows use conversions/delivered; ad/adset rows use conversions/clicks. - Flow rows omit `bounced`/`spam_complaints` (and their rates): Klaviyo flow-series reports do not measure them, so absence means "not tracked", not zero. Campaign rows report them as measured. - Meta ad/adset rows also carry mid-funnel counts `add_to_cart` / `initiate_checkout` (their `*_value` totals only when nonzero), `leads`/`lead_value` (only when nonzero) and, when the row is a video creative (per MetaAd metadata) or the window saw video delivery, the video funnel: `video_views` (Meta 30-second views, not 3-second) + `video_views_p25/p50/p75/p95/p100` percentile completions — a delivered video nobody watched shows measured zeros. The video keys are omitted entirely for static/unknown-media rows with no video delivery — a structural gap, not a measured 0. Adset rows can mix formats, so they use the delivery signal only. - `landing_page_views`, `video_3_sec_views` (hook-rate numerator), and `thruplays` appear only when EVERY row in the window carries them (synced after the KRE-279 extension) — a window crossing the rollout boundary omits them instead of publishing a partial total next to full-window spend. Re-sync history to fill. Absence means "not fully synced for this window", never a measured 0. `video_avg_watch_time_sec` is an unweighted mean of per-day averages over the reported days. - `cpa` denominator varies by level: Shopify account rows use store orders; attributed-channel account rows and campaign/adset/ad rows use platform conversions/purchases - so `cpa` is not directly comparable across channels or levels. - All monetary values are in the brand's single base currency; there is no per-row currency field. - Blended figures are summed from each account's own rows, so every derived ratio (roas, cpa, ctr, cpm, ...) is Σ numerator / Σ denominator across the accounts — never the average of per-account ratios. - Results reflect data that has already been synced/materialized. Call `get_brand_context` before this tool and disclose its readiness warnings before interpreting rows. Empty `rows` may mean a channel is not yet synced rather than genuinely zero activity.

get_performance

Compare provider engagement, observed-attempt bounce rates and complaints. Defaults to 28 completed days versus the preceding 28. Rates and deltas are fractions. Includes daily counts, period bounce mix, stored message/flow evidence, campaign send-date trends, collection coverage and freshness. Unknown ownership is retained. Daily unique opens are not period-unique recipients; incomplete or invalid rates are null with a reason. Account-total fallback measurements are excluded from this report. Read them through query on klaviyo_deliverability_daily with grain=account; they have no provider attribution. Collection coverage explains when fallback occurred. Account selectors use the same tenant-scoped account names/IDs/groups as get_performance.

get_deliverability