`get_creative_insights`

Adlyse’s creative-analytics rollups — the dashboard’s Creative Analytics tab as one payload: period summary, performance grouped by a dimension, lifecycle/platform mix, creative-fatigue rollup, and launch velocity. Performance defaults to fixed 30-day windows or can use an inclusive date range of up to 90 days. Fatigue and velocity remain current-health signals.

Use for creative strategy questions: which angles/hooks win, is spend stuck on stale creatives, what’s fatiguing. For the creatives themselves (copy + media URLs), use the ads server’s list_creative_library.

Parameters#

Name	Type	Required	Default	Description
`ad_account_id`	string	no		Scope to one ad account; omit for the whole org
`dimension`	string	no	`angle`	`angle` \| `hook` \| `format_style` (vision-tagged creatives) \| `format` \| `platform`
`platform`	string	no		`meta_ads` \| `google_ads` \| `microsoft_ads` (platforms whose creatives Adlyse syncs)
`lifecycle`	string	no		`draft` \| `active` \| `paused` \| `retired` \| `archived`
`date_from`	string	no		Inclusive start date (`YYYY-MM-DD`); requires `date_to`
`date_to`	string	no		Inclusive end date (`YYYY-MM-DD`); requires `date_from`; maximum range is 90 days

Returns#

json

{
  "summary": {
    "current": { "spend": 8210.4, "impressions": 410000, "clicks": 5200, "revenue": 24100.2 },
    "prior": { "spend": 7930.1, "impressions": 388000, "clicks": 4800, "revenue": 21050.7 },
    "scored_count": 120
  },
  "dimension": "angle",
  "by_dimension": [
    {
      "value": "social_proof",
      "creative_count": 14,
      "spend_30d": 3120.5,
      "impressions_30d": 160000,
      "clicks_30d": 2100,
      "conversions_30d": 96,
      "revenue_30d": 9400.1,
      "avg_ctr_30d": 0.0131,
      "avg_roas_30d": 3.4
    }
  ],
  "mix": { "lifecycle": [], "platform": [] },
  "fatigue": {
    "counts": { "healthy": 61, "watch": 9, "fatigued": 4 },
    "total_scored": 74,
    "fatiguing": [
      {
        "creative_id": "ad_crtv_abc123",
        "name": "Summer hero v2",
        "platform": "meta_ads",
        "spend_30d": 1240.5,
        "roas_30d": 2.1,
        "level": "fatigued",
        "ctr_decline_pct": -41.2,
        "frequency": 4.3
      }
    ]
  },
  "velocity": {
    "new_last_7": 2,
    "new_last_14": 5,
    "new_last_30": 11,
    "active_count": 74,
    "total_spend_30d": 8210.4,
    "fresh_spend_share": 0.28
  },
  "performance_range": null,
  "filters": {
    "ad_account_id": null,
    "platform": null,
    "lifecycle": null,
    "date_from": null,
    "date_to": null
  },
  "source": "adlyse.creative_insights@v1"
}

Angle/hook/format_style group only vision-tagged creatives (the tagging pipeline); format/platform aggregate the whole library. summary.prior is null when the older window has no data. When dates are provided, performance_range contains the resolved selected/prior dates and coverage metadata, and range rows use neutral metric keys such as spend, conversions, and revenue rather than *_30d.

Errors#

`error_type`	When
`auth_error`	Missing / invalid API key
`not_found`	Ad account doesn’t belong to your org
`validation_error`	Invalid `dimension` / `platform` / `lifecycle`

get_creative_insights

Parameters#

Name	Type	Required	Default	Description
`ad_account_id`	string	no		Scope to one ad account; omit for the whole org
`dimension`	string	no	`angle`	`angle` \| `hook` \| `format_style` (vision-tagged creatives) \| `format` \| `platform`
`platform`	string	no		`meta_ads` \| `google_ads` \| `microsoft_ads` (platforms whose creatives Adlyse syncs)
`lifecycle`	string	no		`draft` \| `active` \| `paused` \| `retired` \| `archived`
`date_from`	string	no		Inclusive start date (`YYYY-MM-DD`); requires `date_to`
`date_to`	string	no		Inclusive end date (`YYYY-MM-DD`); requires `date_from`; maximum range is 90 days

Returns#

json

{
  "summary": {
    "current": { "spend": 8210.4, "impressions": 410000, "clicks": 5200, "revenue": 24100.2 },
    "prior": { "spend": 7930.1, "impressions": 388000, "clicks": 4800, "revenue": 21050.7 },
    "scored_count": 120
  },
  "dimension": "angle",
  "by_dimension": [
    {
      "value": "social_proof",
      "creative_count": 14,
      "spend_30d": 3120.5,
      "impressions_30d": 160000,
      "clicks_30d": 2100,
      "conversions_30d": 96,
      "revenue_30d": 9400.1,
      "avg_ctr_30d": 0.0131,
      "avg_roas_30d": 3.4
    }
  ],
  "mix": { "lifecycle": [], "platform": [] },
  "fatigue": {
    "counts": { "healthy": 61, "watch": 9, "fatigued": 4 },
    "total_scored": 74,
    "fatiguing": [
      {
        "creative_id": "ad_crtv_abc123",
        "name": "Summer hero v2",
        "platform": "meta_ads",
        "spend_30d": 1240.5,
        "roas_30d": 2.1,
        "level": "fatigued",
        "ctr_decline_pct": -41.2,
        "frequency": 4.3
      }
    ]
  },
  "velocity": {
    "new_last_7": 2,
    "new_last_14": 5,
    "new_last_30": 11,
    "active_count": 74,
    "total_spend_30d": 8210.4,
    "fresh_spend_share": 0.28
  },
  "performance_range": null,
  "filters": {
    "ad_account_id": null,
    "platform": null,
    "lifecycle": null,
    "date_from": null,
    "date_to": null
  },
  "source": "adlyse.creative_insights@v1"
}

error_type

When

auth_error

Missing / invalid API key

not_found

Ad account doesn’t belong to your org

validation_error

Invalid dimension / platform / lifecycle