Compute creative fatigue

Returns a deterministic creative fatigue score with its components (hook rate and CTR trajectories, frequency trend, CPM in context) and a status. Pass adId to score one ad, or omit it to score the launch aggregated at level, over the last days days. Values are computed from live daily insights on the ad platform.

GET

/v1/brands/{brandId}/launches/{launchId}/creative-fatigue

Authorization

bearerAuth

headerAuthorizationBearer <token>

An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.

Path Parameters

brandId*integer

The brand the request acts on. Every brand-scoped resource lives under its brand.

launchId*string

The campaign launch (batch) id.

Query Parameters

adId?string

Optional ad-platform ad id to score a single ad. When omitted, scores the aggregated series at the chosen level.

Length1 <= length

level?string

Insight level; defaults to 'ad' since fatigue is a per-creative concept.

Default"ad"

Value in"campaign""adset""ad"

days?integer

Lookback window in days. Defaults to 30.

Range3 <= value <= 90

Default30

Response Body

Compute creative fatigue

application/json

response

score*number|null

components*

status*string

Value in"insufficient data""no fatigue""early""active""exhausted"

daysAnalyzed*number

source*string

asOf?string

ISO time of the live provider read behind this response. Set on MCP and API responses, which may be served from the short metrics cache.

[key: string]?unknown

curl -X GET "https://example.com/v1/brands/0/launches/string/creative-fatigue" \  -H "Authorization: Bearer koast_sk_..."

{  "score": 0,  "components": {    "hookRateTrajectory": 0,    "ctrTrajectory": 0,    "frequencyTrend": 0,    "cpmInContext": 0,    "property1": null,    "property2": null  },  "status": "insufficient data",  "daysAnalyzed": 0,  "source": "insights-daily",  "asOf": "string",  "property1": null,  "property2": null}

Required scope: read. CLI: koast compute-creative-fatigue, see Launches commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.