Get metrics

Returns performance totals for the launch at level (campaign, ad set or ad) for datePreset (default today): spend, impressions, reach, clicks, link CTR, CPM, frequency, CPC, results, cost per result, hook rate and ROAS. Pass id to scope to one entity. Values are live reads from the ad platform; a null metric means it is unknown, not zero.

GET

/v1/brands/{brandId}/launches/{launchId}/metrics

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

level*string

Which level to pull metrics at.

Value in"campaign""adset""ad"

datePreset?string

Reporting date preset. If omitted, defaults to today. Use last_7d / last_28d / last_30d / last_90d / this_month / last_month as needed. Every last_Nd preset ENDS YESTERDAY and does not include today, so a campaign that only started yesterday reads as zero under last_7d, use today or yesterday to see it, and say which window a number came from. For "lifetime" / "all time" / "since launch", use maximum, NOT "lifetime" (it is not an accepted value). Arbitrary start/end date ranges are not supported by the backend.

Value in"today""yesterday""this_week_sun_today""last_7d""last_14d""last_28d""last_30d""last_90d""this_month""last_month""maximum"

id?string

Optional entity id to scope to. Omit for all entities at this level.

Length1 <= length

Response Body

Get metrics

application/json

response

level*string

campaigns*array<>

campaignLaunchId?string

The launch these rows belong to, echoed back so a second read can be scoped to the same launch without guessing.

isExample*boolean

datePreset*string

dataAvailability?string

Value in"NO_LIVE_ENTITIES""OUT_OF_WINDOW""AVAILABLE"

dateRange?

windowCap?

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/metrics?level=campaign" \  -H "Authorization: Bearer koast_sk_..."

{  "level": "campaign",  "campaigns": [    {      "internalId": "string",      "name": "string",      "isMock": true,      "metaCampaignId": "string",      "metaAdsetId": "string",      "metaAdId": "string",      "campaignId": "string",      "adsetId": "string",      "adId": "string",      "entityId": "string",      "actionType": "string",      "displayStatus": "LIVE",      "providerStatus": "string",      "spend": 0,      "impressions": 0,      "reach": 0,      "clicks": 0,      "ctr": 0,      "cpm": 0,      "frequency": 0,      "costPerClick": 0,      "results": 0,      "costPerResult": 0,      "hookRate": 0,      "purchaseRoas": 0,      "property1": null,      "property2": null    }  ],  "campaignLaunchId": "string",  "isExample": true,  "datePreset": "string",  "dataAvailability": "NO_LIVE_ENTITIES",  "dateRange": {    "start": "string",    "end": "string",    "property1": null,    "property2": null  },  "windowCap": {    "requested": "string",    "maxDays": 0,    "property1": null,    "property2": null  },  "asOf": "string",  "property1": null,  "property2": null}

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