Ads | Marsial Docs

Ad campaigns on Meta, Google, LinkedIn, TikTok, Pinterest, X and Reddit through an ads connection (platform meta-ads, google-ads…): list them with spend and results, pause, resume, change budgets, boost published posts, create campaigns and send conversions. Budgets are whole currency units, never cents.

List ad accounts

GET/v1/accounts/{id}/ads/ad-accounts

The ad accounts an ads connection reaches. Their id is the adAccountId of every other ads call.

Parameters

idstringrequired

Response 200

data []

idstringrequired
Send it as adAccountId (Meta act_…, Google customer id…).
namestringrequired
currencystring
Budgets and bids are whole units of it.
timezonestring
usablebooleanrequired
False when the network will not run ads on it (disabled, no payment method…).

curl "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/ad-accounts" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/ad-accounts', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/ad-accounts",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

List campaigns with their results

GET/v1/accounts/{id}/ads/campaigns

Campaigns created in Marsial and in the network's ads manager, with spend, impressions and clicks for the period.

Parameters

idstringrequired
adAccountIdstring
Only this ad account (GET …/ads/ad-accounts).
max 100
fromstring
First day of the metrics (YYYY-MM-DD). 90 days ago by default.
tostring
Last day of the metrics (YYYY-MM-DD). Today by default.

Response 200

data []

idstringrequired
The network's campaign id.
accountIdstringrequired
The ads connection.
networkstringrequired
facebook, instagram, google, linkedin, tiktok, pinterest, twitter or reddit.
namestringrequired
statusstringrequired
reviewStatusstring
adAccountIdstringrequired
adAccountNamestring
currencystring
budgetobject
budget
- amountnumberrequired
- typestringrequired
adCountintegerrequired
max 9,007,199,254,740,991
metricsobjectrequired
metrics
- spendnumberrequired
- impressionsnumberrequired
- clicksnumberrequired
- reachnumber
- conversionsnumber
- ctrnumber
- cpcnumber
- cpmnumber

curl "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns?from=2026-10-01&to=2026-10-31', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns?from=2026-10-01&to=2026-10-31",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Create a campaign

POST/v1/accounts/{id}/ads/campaigns

Campaign, ad group and ad in one call, in the network's own terms (adAccountId, goal, budgetAmount, budgetType, the creative, targeting…): see the ads guide. Marsial fills the connection in.

Parameters

idstringrequired

Body

Response 201

data

campaignIdstring | nullrequired

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Pause, resume or change the budget

PATCH/v1/accounts/{id}/ads/campaigns/{campaignId}

Pausing always applies at once. Resuming and budgets answer 202 when the workspace requires approval for the caller.

Parameters

idstringrequired
campaignIdstringrequired

Body

statusstring
Values: active · paused
budgetobject
budget
- amountnumberrequired
  Whole units of the ad account currency: 50 is 50.00, never cents.
- typestringrequired
  Values: daily · lifetime

Response 200

data

idstringrequired
The network's campaign id.
accountIdstringrequired
The ads connection.
networkstringrequired
facebook, instagram, google, linkedin, tiktok, pinterest, twitter or reddit.
namestringrequired
statusstringrequired
reviewStatusstring
adAccountIdstringrequired
adAccountNamestring
currencystring
budgetobject
budget
- amountnumberrequired
- typestringrequired
adCountintegerrequired
max 9,007,199,254,740,991
metricsobjectrequired
metrics
- spendnumberrequired
- impressionsnumberrequired
- clicksnumberrequired
- reachnumber
- conversionsnumber
- ctrnumber
- cpcnumber
- cpmnumber

curl -X PATCH "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns/120210000000" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused"
  }'

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns/120210000000', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "paused"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.patch(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns/120210000000",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "status": "paused"
    },
)
data = res.json()["data"]

Send conversions

POST/v1/accounts/{id}/ads/conversions

Server-side events for the network: Meta Conversions API, Google offline conversions, LinkedIn and TikTok.

Parameters

idstringrequired

Body

Response 200

data

receivedintegerrequired
max 9,007,199,254,740,991

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/conversions" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/conversions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/conversions",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Boost a published post

POST/v1/posts/{id}/boost

Turns one published copy of the post (its accountId) into an ad paid by adAccountId. The network reviews it before it delivers.

Parameters

idstringrequired

Body

accountIdstringrequired
The post's account whose published copy to promote.
adAccountIdstringrequired
The ad account that pays (GET /v1/accounts/{id}/ads/ad-accounts on the ads connection).
max 100
namestringrequired
max 200
goalstringrequired
What the network optimises for. Each network takes a subset.
Values: engagement · traffic · awareness · video_views · lead_generation · conversions · app_promotion
budgetobjectrequired
budget
- amountnumberrequired
  Whole units of the ad account currency: 50 is 50.00, never cents.
- typestringrequired
  Values: daily · lifetime
startDatestring (date-time)
endDatestring (date-time)
Required with a lifetime budget.
targetingobject
targeting
- countriesstring[]
  ISO country codes.
  max 50 items
- ageMininteger
  min 13max 65
- ageMaxinteger
  min 13max 65
callToActionstring
e.g. LEARN_MORE, SHOP_NOW; needs linkUrl.
max 50
linkUrlstring (uri)

Response 201

data

campaignIdstring | nullrequired

curl -X POST "https://api.marsial.dev/v1/posts/pst_7q1w0e/boost" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "adAccountId": "act_120210",
    "name": "Autumn",
    "goal": "traffic",
    "budget": {
      "amount": 40,
      "type": "daily"
    }
  }'

const res = await fetch('https://api.marsial.dev/v1/posts/pst_7q1w0e/boost', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "adAccountId": "act_120210",
    "name": "Autumn",
    "goal": "traffic",
    "budget": {
      "amount": 40,
      "type": "daily"
    }
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/posts/pst_7q1w0e/boost",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "adAccountId": "act_120210",
        "name": "Autumn",
        "goal": "traffic",
        "budget": {
            "amount": 40,
            "type": "daily"
        }
    },
)
data = res.json()["data"]

List ad changes waiting for approval

GET/v1/ads/requests

With requireAdsApproval on, members and AI agents (MCP) ask for ad changes that spend money instead of making them. Newest first, with what became of each.

Parameters

statusstring
Only changes in this state; all of them, newest first, otherwise.
Values: pending · approved · rejected · failed

Response 200

data []

idstringrequired
adr_…
changeobject | object | objectrequired
What reaches the network on approval.
change
- kind"update_campaign"required
- accountIdstringrequired
- campaignIdstringrequired
- campaignNamestringrequired
- currencystring
- currentobjectrequired
  The campaign when the change was asked for.
  current
  - statusstringrequired
  - budgetobject
    budget
    amountnumberrequired
    typestringrequired
- statusstring
  Values: active · paused
- budgetobject
  budget
  - amountnumberrequired
  - typestringrequired
statusstringrequired
failed: approved, but the network refused it (see error).
Values: pending · approved · rejected · failed
requestedBystring
The user who asked, or for whom an AI agent asked.
viastringrequired
Values: agent · person
requestedAtstring (date-time)required
decidedBystring
decidedAtstring (date-time)
notestring
campaignIdstring
The campaign an approved boost or new campaign created.
errorstring

curl "https://api.marsial.dev/v1/ads/requests?status=pending" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/ads/requests?status=pending', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/ads/requests?status=pending",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Get an ad change request

GET/v1/ads/requests/{id}

Parameters

idstringrequired

Response 200

data

idstringrequired
adr_…
changeobject | object | objectrequired
What reaches the network on approval.
change
- kind"update_campaign"required
- accountIdstringrequired
- campaignIdstringrequired
- campaignNamestringrequired
- currencystring
- currentobjectrequired
  The campaign when the change was asked for.
  current
  - statusstringrequired
  - budgetobject
    budget
    amountnumberrequired
    typestringrequired
- statusstring
  Values: active · paused
- budgetobject
  budget
  - amountnumberrequired
  - typestringrequired
statusstringrequired
failed: approved, but the network refused it (see error).
Values: pending · approved · rejected · failed
requestedBystring
The user who asked, or for whom an AI agent asked.
viastringrequired
Values: agent · person
requestedAtstring (date-time)required
decidedBystring
decidedAtstring (date-time)
notestring
campaignIdstring
The campaign an approved boost or new campaign created.
errorstring

curl "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/ads/requests/adr_3m8p2q', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Approve or reject an ad change

POST/v1/ads/requests/{id}/review

Owners and admins (and API keys). Approving sends it to the network at once; if the network refuses, the request ends failed with the reason. AI agents cannot review.

Parameters

idstringrequired

Body

decisionstringrequired
approve sends the change to the network now; reject drops it.
Values: approve · reject
notestring
Why, for whoever asked for it.
max 1,000

Response 200

data

idstringrequired
adr_…
changeobject | object | objectrequired
What reaches the network on approval.
change
- kind"update_campaign"required
- accountIdstringrequired
- campaignIdstringrequired
- campaignNamestringrequired
- currencystring
- currentobjectrequired
  The campaign when the change was asked for.
  current
  - statusstringrequired
  - budgetobject
    budget
    amountnumberrequired
    typestringrequired
- statusstring
  Values: active · paused
- budgetobject
  budget
  - amountnumberrequired
  - typestringrequired
statusstringrequired
failed: approved, but the network refused it (see error).
Values: pending · approved · rejected · failed
requestedBystring
The user who asked, or for whom an AI agent asked.
viastringrequired
Values: agent · person
requestedAtstring (date-time)required
decidedBystring
decidedAtstring (date-time)
notestring
campaignIdstring
The campaign an approved boost or new campaign created.
errorstring

curl -X POST "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q/review" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve"
  }'

const res = await fetch('https://api.marsial.dev/v1/ads/requests/adr_3m8p2q/review', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "decision": "approve"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q/review",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "decision": "approve"
    },
)
data = res.json()["data"]