API referenceLaunches

List Koast batches

Lists the brand's Koast launches (batches), drafts and published, with their status and campaign, ad set and ad counts. Filter by status or by a title substring with search.

GET
/v1/brands/{brandId}/launches

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.

Query Parameters

accountId?string

Ad account id (act_xxx on Meta). Optional, defaults to current page context.

status?string

Filter by lifecycle status.

Value in"DRAFT""IMPORTED""PENDING""RUNNING""COMPLETED""COMPLETED_WITH_ISSUES""ACTION_REQUIRED""FAILED""CANCELLED"
search?string

Substring match on batch title.

page?integer
Range0 < value <= 9007199254740991
Default1
limit?integer

Page size.

Range1 <= value <= 100
Default50
cursor?string

Opaque cursor from the previous page's nextCursor. Omit for the first page.

Response Body

List Koast batches

application/json
  1. response
accountId*string|null
total*number
page*number
limit*number
batches*array<>
nextCursor*|

Pass as cursor to read the next page. Null when there is no next page.

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.

curl -X GET "https://example.com/v1/brands/0/launches" \  -H "Authorization: Bearer koast_sk_..."
{  "accountId": "string",  "total": 0,  "page": 0,  "limit": 0,  "batches": [    {      "id": "string",      "title": "string",      "description": "string",      "status": "string",      "createdAt": "string",      "updatedAt": "string",      "campaignsCount": 0,      "adsetsCount": 0,      "adsCount": 0    }  ],  "nextCursor": "string",  "asOf": "string"}

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

Update RedTrack spend push

Turns the spend push into RedTrack on or off. When on, Koast places each mapped campaign's spend for today into its RedTrack campaign every hour, and yesterday's final spend once after midnight in the ad account timezone. RedTrack must be connected first. Changing the brand's RedTrack key turns the push off. Requires an organization owner or admin.

Create campaign launch

Creates an empty launch (batch) under the brand and returns its id. The launch holds no campaigns until you add one. title defaults to "Untitled Batch".