API referenceAd Accounts

List ad account campaigns

Lists every campaign in the ad account on the ad platform, including those not imported into Koast. Filter by statusFilter or by a case-insensitive name substring with nameQuery. Values are live reads from the ad platform.

GET
/v1/brands/{brandId}/ad-accounts/{accountId}/campaigns

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.

accountId*string

The ad account id (act_… on Meta, biz_… on Whop).

Query Parameters

statusFilter?array<string>

Filter by status: ACTIVE, PAUSED, ARCHIVED

nameQuery?string

Case-insensitive substring to match campaign names. ALWAYS pass this when the user named a specific campaign (e.g. "meta test campaign"), the account can hold hundreds of campaigns and this returns only the matches with their ids.

Length1 <= length
cursor?string

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

limit?integer

Page size.

Range1 <= value <= 100
Default50

Response Body

List ad account campaigns

application/json
  1. response
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.

campaigns*array<>
totalInAccount*number
matched*number
nameQuery*string|null
nextCursor*|

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

curl -X GET "https://example.com/v1/brands/0/ad-accounts/string/campaigns" \  -H "Authorization: Bearer koast_sk_..."
{  "asOf": "string",  "campaigns": [    {      "id": "string",      "name": "string",      "status": "string",      "effective_status": "string",      "objective": "string",      "brandId": "string",      "budget": {        "period": "string",        "amountMinorUnits": 0      },      "budgetLevel": "string",      "property1": null,      "property2": null    }  ],  "totalInAccount": 0,  "matched": 0,  "nameQuery": "string",  "nextCursor": "string"}

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

Get team activity log

Returns the team activity log for the brand, who changed what and when, over the last days days. Filter by userId or entityId. activities is the cursor-paginated collection (limit, cursor, nextCursor); summary counts the activities of the returned page.

List lead forms

Lists the instant lead forms that exist on the Page pageId, as { id, name }. Values are live reads from the ad platform.