Docs
Open SmallForce

CLI

SmallForce CLI: Meta Ads commands

Manage Meta, Google, and TikTok Ads through organization-scoped SmallForce resources

This page covers 148 smallforce ads commands. It is generated from SmallForce CLI 0.1.17; run smallforce ads --help (or any command with --help) to see the same reference for the version you have installed. New to the CLI? Start with installation and authentication and JSON output.

Agent workflow:
  Google Ads:
    ads google --help

  TikTok Ads:
    ads tiktok --help

  Meta Ads (existing top-level commands):
  1. social profiles list
     Reuse the profile that owns the Facebook or Instagram connection.
  2. ads connections connect --profile <profileId> --via facebook
     Share authUrl when returned; same-token connections may complete immediately.
  3. ads connections list --json
     Resolve the ads connection id and inspect its activation state.
  4. ads connections activate <socialAccountId>
     Activate the monthly advertising connection when required.
  5. ads accounts sync <socialAccountId>
     Import the Meta ad accounts visible to that connection.
  6. ads accounts list --json
     Use the returned local ad-account id as --account.
  7. ads targeting search "<audience>" --account <adAccountId>
  8. ads campaigns validate --input-file draft.json
  9. ads campaigns create --input-file draft.json

To see what needs attention across Meta, Google, and TikTok (rejected ads,
delivery issues, payment problems, spend without results, capped budgets, lost
connections, failing syncs), run ads alerts list.

For asynchronous Meta Insights, use ads reports create, then ads reports wait
with the returned local report ID. Use ads reports get to page completed rows.

Meta campaigns are created paused. Run campaigns preflight before changing a
campaign to active. Complex mutation payloads accept --input '<json>',
--input-file <path>, or --input-file - for stdin.

Every leaf command supports --json. Use each leaf's --help for ID sources,
payload shapes, safety notes, and next commands. Google Ads and TikTok Ads live
under their explicit provider namespaces; existing top-level ads commands are
Meta Ads.

Common options

Most commands accept these options as well as their own. Every command also accepts -h, --help.

OptionDescription
--api-key <key>SmallForce API key, or set SMALLFORCE_API_KEY
--backend-url <url>SmallForce backend URL, or set SMALLFORCE_BACKEND_URL
--jsonPrint stable machine-readable JSON
--textPrint human-readable text
--format <format>Output format: text or json

smallforce ads connections

Connect and activate Meta Ads credentials

smallforce ads connections connect

Create or reuse a Meta Ads connection

Usage: smallforce ads connections connect [options]

OptionDescription
--profile <profileId>Social profile id from social profiles list
--via <platform>Parent platform: facebook or instagram (default: “facebook”)
--provider-account <actId>Limit provider sync to one act_ account; repeatable (default: [])
--redirect-url <url>Browser destination after authorization
--login-mode <mode>Meta authorization: classic or business
--page-id <id>Granted Meta Page ID for business login
--forceStart a fresh authorization
--headlessRequest a headless provider authorization flow

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce ads connections connect --profile <profileId> --via facebook
  $ smallforce ads connections connect --profile <profileId> --via instagram --provider-account act_123 --json

Meta uses the existing Facebook or Instagram token when possible. Share authUrl
if one is returned. The returned socialAccountId identifies the ads connection,
not an individual Meta ad account.

smallforce ads connections list

List Meta Ads connections and activation state

Usage: smallforce ads connections list [options]

OptionDescription
--profile <profileId>Filter by one social profile
--include-deletedInclude disconnected connections

Also accepts the common options listed at the top of this page.

Use the returned local connection ID with connections activate, accounts sync,
or connections disconnect.

Example:
  $ smallforce ads connections list --json

smallforce ads connections activate

Activate billing for one Meta Ads connection

Usage: smallforce ads connections activate [options] <socialAccountId>

ArgumentDescription
socialAccountIdLocal connection id

Also accepts the common options listed at the top of this page.

The plan includes 5 connected accounts (social accounts and ad connections
together). Inside that allowance this charges nothing; beyond it, it charges the
monthly extra-account rate in SmallForce Credits. It is idempotent while the
current billing period is active.

Next:
  ads accounts sync <socialAccountId>

smallforce ads connections disconnect

Disconnect one Meta Ads credential

Usage: smallforce ads connections disconnect [options] <socialAccountId>

ArgumentDescription
socialAccountIdLocal connection id

Also accepts the common options listed at the top of this page.

This disconnects the provider credential and marks its local connection
inactive. It is safe to repeat after a confirmed disconnect.

Example:
  $ smallforce ads connections disconnect <socialAccountId>

smallforce ads accounts

Synchronize and inspect Meta Ads accounts

smallforce ads accounts list

List local Meta Ads account IDs

Usage: smallforce ads accounts list [options]

OptionDescription
--connection <socialAccountId>Filter by one Meta Ads connection

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce ads accounts list
  $ smallforce ads accounts list --connection <socialAccountId> --json

Use each returned ID as --account in Meta Ads operation commands.

smallforce ads accounts sync

Synchronize provider accounts for one Meta Ads connection

Usage: smallforce ads accounts sync [options] <socialAccountId>

ArgumentDescription
socialAccountIdLocal connection id

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce ads accounts sync <socialAccountId>
  $ smallforce ads accounts sync <socialAccountId> --json

Next:
  ads accounts list --connection <socialAccountId>

smallforce ads accounts create

Create a Meta ad account in your business portfolio

Usage: smallforce ads accounts create [options]

OptionDescription
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Input: {"socialAccountId":"<local connection UUID>","businessId":"<Meta business ID>","name":"My business","currency":"USD","timezoneId":1,"idempotencyKey":"<UUID>"}
Use Meta numeric timezone IDs. Payment setup remains in Meta. Keep the same key when checking a previous attempt; do not repeat an uncertain creation with a new key.

smallforce ads accounts live

Get ad account live entities

Usage: smallforce ads accounts live [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.status (optional): string
    Comma-separated Meta `effective_status` values to keep: ACTIVE, PAUSED, IN_PROCESS, WITH_ISSUES, DELETED, ARCHIVED, and CAMPAIGN_PAUSED (ad sets only; the campaigns level ignores it). Defaults to every status except DELETED and...
  query.level (optional): "campaign" | "adSet"
    Read only one level. Required with `after`. Both levels are read when omitted.
  query.limit (optional): integer
    Maximum rows per level in this response.
  query.after (optional): string
    Cursor from `paging.campaigns.after` or `paging.adSets.after` of a previous response.

Request skeleton:
{
  "query": {
    "status": "PAUSED"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts activity

Read the Meta ad-account activity log

Usage: smallforce ads accounts activity [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.since (optional): string(date)
    Start of range (YYYY-MM-DD).
  query.until (optional): string(date)
    End of range (YYYY-MM-DD).
  query.objectId (optional): local campaign, ad_set, or ad reference
    Client-side filter to one object id (campaign, ad set / ad group or ad). Use a SmallForce-local campaign, ad_set, or ad reference; raw provider IDs are rejected.
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "since": "2026-08-01",
    "until": "2026-08-01"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts studies

List Meta ad studies

Usage: smallforce ads accounts studies [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fields (optional): string
    Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "fields": "<fields>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts businesses

List Meta businesses visible to the connection

Usage: smallforce ads accounts businesses [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "limit": 25
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts labels

List Meta ad-account labels

Usage: smallforce ads accounts labels [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
    Meta only. Rows per page.
  query.after (optional): string
    Meta only. Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "limit": 25
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts high-demand-periods

List high-demand periods for a campaign or ad set

Usage: smallforce ads accounts high-demand-periods [options] <targetId>

ArgumentDescription
targetIdSmallForce-local campaign or ad-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--target-kind <kind>campaign or ad_set
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "limit": 25
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts create-high-demand-period

Create a Meta high-demand period

Usage: smallforce ads accounts create-high-demand-period [options] <targetId>

ArgumentDescription
targetIdSmallForce-local campaign or ad-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--target-kind <kind>campaign or ad_set
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.budgetValue (required): number
    With ABSOLUTE, a budget in the ad account's currency in WHOLE units (50 = $50.00). With MULTIPLIER, a factor of the existing budget (2 = double it) and NOT a currency amount.
  body.budgetValueType (required): "ABSOLUTE" | "MULTIPLIER"
  body.timeStart (required): integer
    Unix seconds, on a 15-minute boundary (:00, :15, :30, :45).
  body.timeEnd (required): integer
    Unix seconds, on a 15-minute boundary and after timeStart.
  body.recurrenceType (optional): "ONE_TIME" | "WEEKLY" | "MONTHLY"
  body.currency (optional): string
    Ad account currency, for the ABSOLUTE minor-unit conversion. Ignored for MULTIPLIER.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "budgetValue": 1,
    "budgetValueType": "ABSOLUTE",
    "timeStart": 1,
    "timeEnd": 1
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts value-rule-sets

List Meta value rule sets

Usage: smallforce ads accounts value-rule-sets [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page. Meta does not document paging on this edge; `after` comes back null when it omits cursors.

Request skeleton:
{
  "query": {
    "limit": 25
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts create-value-rule-set

Create a Meta value rule set

Usage: smallforce ads accounts create-value-rule-set [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
  body.rules (required): array<object{name, adjustSign, adjustValue, criteria}>
    Evaluated in order; the first matching rule wins.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "rules": [
      {
        "name": "Example Meta Ads resource",
        "adjustSign": "INCREASE",
        "adjustValue": 1,
        "criteria": [
          {
            "criteriaType": "AGE",
            "operator": "CONTAINS",
            "criteriaValues": [
              "<criteriaValues>"
            ],
            "criteriaValueTypes": [
              "<criteriaValueTypes>"
            ]
          }
        ]
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts get-value-rule-set

Read a Meta value rule set

Usage: smallforce ads accounts get-value-rule-set [options] <targetId>

ArgumentDescription
targetIdSmallForce-local value-rule-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts update-value-rule-set

Update a Meta value rule set

Usage: smallforce ads accounts update-value-rule-set [options] <targetId>

ArgumentDescription
targetIdSmallForce-local value-rule-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
    Required: the update replaces the whole set.
  body.rules (required): array<object{name, adjustSign, adjustValue, criteria}>
    The COMPLETE rule list. Omitting a rule deletes it on Meta.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "rules": [
      {
        "name": "Example Meta Ads resource",
        "adjustSign": "INCREASE",
        "adjustValue": 1,
        "criteria": [
          {
            "criteriaType": "AGE",
            "operator": "CONTAINS",
            "criteriaValues": [
              "<criteriaValues>"
            ],
            "criteriaValueTypes": [
              "<criteriaValueTypes>"
            ]
          }
        ]
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts delete-value-rule-set

Delete a Meta value rule set

Usage: smallforce ads accounts delete-value-rule-set [options] <targetId>

ArgumentDescription
targetIdSmallForce-local value-rule-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts finance

Read Meta ad-account finance details

Usage: smallforce ads accounts finance [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts update

Update Meta ad-account defaults

Usage: smallforce ads accounts update [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (optional): string
    New ad account name.
  body.spendCap (optional): value
    Account spend cap in whole currency units; null removes it.
  body.resetAmountSpent (optional): boolean
    Restart the amount counted against the cap from zero. Cannot be combined with spendCap null.
  body.defaultDsaBeneficiary (optional): string
    Legal entity benefiting from ads on this ad account
  body.defaultDsaPayor (optional): string
    Legal entity paying for ads on this ad account. Defaults to defaultDsaBeneficiary when omitted. Requires defaultDsaBeneficiary.
  body.trackingUrlTemplate (optional): string
  body.finalUrlSuffix (optional): string
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts dsa-defaults

Read Meta DSA beneficiary and payor defaults

Usage: smallforce ads accounts dsa-defaults [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts dsa-recommendations

Read Meta DSA recommendations

Usage: smallforce ads accounts dsa-recommendations [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts custom-conversions

List Meta custom conversions

Usage: smallforce ads accounts custom-conversions [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts create-custom-conversion

Create a Meta custom conversion

Usage: smallforce ads accounts create-custom-conversion [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
    Also the reuse key, together with pixelId.
  body.pixelId (required): local tracking_tag reference
    Meta pixel id (event_source_id). From GET /v1/accounts/{accountId}/tracking-tags. Use a SmallForce-local tracking_tag reference; raw provider IDs are rejected.
  body.customEventType (required): string
    Meta custom_event_type, e.g. LEAD, PURCHASE, OTHER.
  body.rule (required): object
    Meta conversion rule, forwarded verbatim.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "pixelId": {
      "$smallforce": {
        "id": "<local tracking_tag UUID>",
        "kind": "tracking_tag"
      }
    },
    "customEventType": "<customEventType>",
    "rule": {}
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads accounts health

Check whether the ad account can run ads now, with a fix link per problem

Usage: smallforce ads accounts health [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads campaigns

Create, review, inspect, and manage Meta Ads campaigns

smallforce ads campaigns list

List Meta Ads campaigns

Usage: smallforce ads campaigns list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--platform <platform>facebook or instagram
--status <status>Campaign status filter
--source <source>all or zernio (default: “all”)
--from <date>Inclusive YYYY-MM-DD start date
--to <date>Inclusive YYYY-MM-DD end date
--page <n>Page number, starting at 1
--limit <n>Campaigns per page, 1 to 100

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce ads campaigns list --account <adAccountId>
  $ smallforce ads campaigns list --account <adAccountId> --status active --from 2026-07-01 --to 2026-07-31 --json

smallforce ads campaigns tree

Read campaigns with nested ad sets and advertisements

Usage: smallforce ads campaigns tree [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--platform <platform>facebook or instagram
--status <status>Campaign status filter
--source <source>all or zernio (default: “all”)
--from <date>Inclusive YYYY-MM-DD start date
--to <date>Inclusive YYYY-MM-DD end date
--page <n>Page number, starting at 1
--limit <n>Campaigns per page, 1 to 100
--campaign <campaignId>Limit to one local campaign id
--include-dailyInclude daily metric rows
--daily-level <level>campaign, adset, or ad
--sort <sort>newest, oldest, spend_desc, or spend_asc

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce ads campaigns tree --account <adAccountId> --campaign <campaignId> --json
  $ smallforce ads campaigns tree --account <adAccountId> --include-daily --daily-level adset --from 2026-07-01 --to 2026-07-31 --json

smallforce ads campaigns analytics

Get summary, daily, and optional breakdown analytics

Usage: smallforce ads campaigns analytics [options] <campaignId>

ArgumentDescription
campaignIdLocal campaign id from campaigns list
OptionDescription
--account <adAccountId>Local id from ads accounts list
--platform <platform>facebook or instagram
--from <date>Inclusive YYYY-MM-DD start date
--to <date>Inclusive YYYY-MM-DD end date
--breakdown <dimension>age, gender, country, publisher_platform, device_platform, or region; repeatable (default: [])

Also accepts the common options listed at the top of this page.

Examples:
  $ smallforce ads campaigns analytics <campaignId> --account <adAccountId>
  $ smallforce ads campaigns analytics <campaignId> --account <adAccountId> --breakdown age --breakdown gender --json

smallforce ads campaigns preflight

Check whether a paused Meta campaign is ready to activate

Usage: smallforce ads campaigns preflight [options] <campaignId>

ArgumentDescription
campaignIdLocal campaign id from campaigns list
OptionDescription
--account <adAccountId>Local id from ads accounts list
--platform <platform>facebook or instagram

Also accepts the common options listed at the top of this page.

Run this before campaigns status <campaignId> active. Blocking issues prevent
activation; warnings are returned without blocking it.

Example:
  $ smallforce ads campaigns preflight <campaignId> --account <adAccountId> --json

smallforce ads campaigns validate

Validate a complete Meta campaign draft without creating it

Usage: smallforce ads campaigns validate [options]

OptionDescription
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Input is the same complete object used by campaigns create. Validation invokes
Meta's validate-only flow and does not create campaign objects. Predictable-
reach drafts are validated as part of quote and reserve instead.

Examples:
  $ smallforce ads campaigns validate --input-file draft.json
  $ cat draft.json | smallforce ads campaigns validate --input-file - --json

smallforce ads campaigns preview

Generate safe Meta placement previews for a campaign draft

Usage: smallforce ads campaigns preview [options]

OptionDescription
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Input is the complete campaign draft plus previewFormats. Supported formats:
  DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD,
  INSTAGRAM_STORY, INSTAGRAM_REELS, FACEBOOK_STORY_MOBILE

Pre-create provider previews currently require an image asset.

Example:
  $ smallforce ads campaigns preview --input-file preview-draft.json --json

smallforce ads campaigns create

Create a complete Meta campaign, ad set, and advertisement

Usage: smallforce ads campaigns create [options]

OptionDescription
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Required top-level draft fields:
  adAccountId, goal, idempotencyKey, mode, name, targeting

Rules:
  mode must be "standalone".
  assetId and creative are required except when goal is page_likes; Meta derives
  the Page destination and LIKE_PAGE call to action for that goal.
  Auction campaigns require budget; lifetime budget requires schedule.endDate.
  targeting requires at least one geographic target.
  The same idempotencyKey safely replays the same request; generate a new UUID
  whenever the request changes.
  Campaigns are created paused. Run campaigns preflight before activation.

Example:
  $ smallforce ads campaigns create --input-file draft.json --json

smallforce ads campaigns update

Update Meta campaign name, CBO budget, bid strategy, or spend cap

Usage: smallforce ads campaigns update [options] <campaignId>

ArgumentDescription
campaignIdLocal campaign id from campaigns list
OptionDescription
--account <adAccountId>Local id from ads accounts list
--platform <platform>facebook or instagram
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Update JSON fields:
  name, budget: { amount, type }, bidStrategy, spendCap

Set spendCap to null to remove it. Campaign budget updates only work for CBO;
use ads ad-sets update for ABO budgets.

Example:
  $ smallforce ads campaigns update <campaignId> --account <adAccountId> --input '{"name":"Fall campaign","budget":{"amount":50,"type":"daily"}}'

smallforce ads campaigns status

Activate or pause one Meta campaign

Usage: smallforce ads campaigns status [options] <campaignId> <status>

ArgumentDescription
campaignIdLocal campaign id from campaigns list
statusactive or paused
OptionDescription
--account <adAccountId>Local id from ads accounts list
--platform <platform>facebook or instagram

Also accepts the common options listed at the top of this page.

Activation automatically runs the same preflight checks as campaigns preflight
and is rejected when blocking issues remain. Pausing does not require preflight.

Examples:
  $ smallforce ads campaigns status <campaignId> active --account <adAccountId>
  $ smallforce ads campaigns status <campaignId> paused --account <adAccountId>

smallforce ads campaigns details

Get live campaign details

Usage: smallforce ads campaigns details [options] <targetId>

ArgumentDescription
targetIdSmallForce-local campaign id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fields (optional): string
    Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers.

Request skeleton:
{
  "query": {
    "fields": "<fields>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads campaigns create-empty

Create an empty Meta campaign

Usage: smallforce ads campaigns create-empty [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
  body.goal (required): "engagement" | "traffic" | "awareness" | "video_views" | "lead_generation" | "lead_conversion" | "job_applicants" | "conversions" | "app_promotion" | "catalog_sales" | "page_likes" | "page_visits"
    Mapped to the ODAX objective (same mapping as POST /v1/ads/create).
  body.isSkadnetworkAttribution (optional): boolean
    Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true....
  body.promotedObject (optional): object
  body.buyingType (optional): "AUCTION" | "RESERVED"
    Every platform buys at auction by default, so this only needs sending on Meta, and only to choose RESERVED. `AUCTION` is accepted on every platform and changes nothing. `RESERVED` (Reach & Frequency) is Meta-only and is rejected with a...
  body.validateOnly (optional): boolean
    Meta and ChatGPT (OpenAI). Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED. `true` on any other platform returns 501...
  body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
  body.budgetAmount (optional): number
    Campaign-level (CBO) budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Requires budgetType.
  body.budgetType (optional): "daily" | "lifetime"
  body.status (optional): "ACTIVE" | "PAUSED"
  body.startDate (optional): string(date-time)
    Reddit only (400 elsewhere). Campaign start (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (`budgetAmount` + `budgetType`, 400 otherwise). Defaults to now.
  body.endDate (optional): string(date-time)
    Reddit only (400 elsewhere). Campaign end (ISO 8601); a value without an offset is read in the ad account time zone. Requires a campaign budget (400 otherwise), and is required for `budgetType: lifetime`.
  body.locationTargetingType (optional): object
    Written on the new campaign.
  body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
    Campaign bid strategy. **Meta** stores `bid_strategy` alongside the budget, so this REQUIRES `budgetAmount` + `budgetType` on the same request (400 without a campaign budget). A campaign carrying a strategy without its `bid_amount`...
  body.bidAmount (optional): number
    Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. - Meta: validated here but NOT stored, since the campaign object only has bid_strategy.
  body.roasAverageFloor (optional): number
    Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "goal": "engagement"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads campaigns delete

Delete a Meta campaign

Usage: smallforce ads campaigns delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local campaign id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.platform (required): "facebook" | "instagram"
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "platform": "facebook"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads campaigns bulk-status

Activate or pause several Meta campaigns

Usage: smallforce ads campaigns bulk-status [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--campaign <campaignId>Local campaign id; repeat for multiple campaigns (default: [])
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.status (required): "active" | "paused"
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "status": "active"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads campaigns duplicate

Duplicate a Meta campaign hierarchy

Usage: smallforce ads campaigns duplicate [options] <targetId>

ArgumentDescription
targetIdSmallForce-local campaign id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.platform (required): "facebook" | "instagram"
  body.deepCopy (optional): boolean
    Copy child ad sets + ads + creatives + targeting
  body.statusOption (optional): "ACTIVE" | "PAUSED" | "INHERITED_FROM_SOURCE"
    PAUSED = clone stays DRAFT, safe default. INHERITED_FROM_SOURCE = mirror each entity's source status per-entity. Duplicating an ACTIVE campaign this way starts a second front of spend.
  body.startTime (optional): string(date-time)
    Reschedule the copied hierarchy's start (ISO 8601). TikTok defaults to a start a few minutes after the copy. - Meta and TikTok: a value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad...
  body.endTime (optional): string(date-time)
    Reschedule the copied hierarchy's end, read like `startTime`; a date-only end runs to 23:59:59 local. Defaults to the source's end.
  body.renameStrategy (optional): "DEEP_RENAME" | "ONLY_TOP_LEVEL_RENAME" | "NO_RENAME"
    Meta's native `rename_strategy` values: - `DEEP_RENAME`: renames the copied campaign and every copied child (ad sets, ads) with `renamePrefix` / `renameSuffix`. - `ONLY_TOP_LEVEL_RENAME`: renames only the copied campaign; children keep...
  body.renamePrefix (optional): string
    Text prepended to each renamed object's name.
  body.renameSuffix (optional): string
    Text appended to each renamed object's name.
  body.syncAfter (optional): boolean
    Trigger ads discovery on the owning account after the copy succeeds
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "platform": "facebook"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads campaigns timeline

Read the Meta Ads performance timeline

Usage: smallforce ads campaigns timeline [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fromDate (optional): string(date)
    Inclusive start of metrics range (YYYY-MM-DD). Defaults to 90 days ago.
  query.toDate (optional): string(date)
    Inclusive end of metrics range (YYYY-MM-DD). Defaults to today. Max 730-day range.
  query.platform (optional): "facebook" | "instagram"
    Restrict to one platform.
  query.compare (optional): "previous"
    Set to `previous` to also return `previousRows` for the period of the same length that ends the day before `fromDate`, with that period as `previousRange`. Needs a `fromDate` (sent or defaulted); `toDate` alone answers 400.

Request skeleton:
{
  "query": {
    "fromDate": "2026-08-01"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads alerts

See what needs attention across Meta, Google, and TikTok ads

smallforce ads alerts list

List ads problems, most severe first: rejected ads, delivery issues, payment problems, spend without results, capped budgets, lost connections, failing syncs

Usage: smallforce ads alerts list [options]

OptionDescription
--account <adAccountId>Only this ad account (local id from ads accounts list)

Also accepts the common options listed at the top of this page.

Alerts come from synced ad data (the last 7 days of metrics), so this makes no
ad-platform call and is safe to run often. An alert id stays the same while the
problem lasts, so compare ids to tell new alerts from ones already reported.
A problem that is fixed disappears from the list.

Example:
  $ smallforce ads alerts list --json
  $ smallforce ads alerts list --account <adAccountId>

smallforce ads businesses

smallforce ads businesses list

List portfolios before creating your first Meta ad account

Usage: smallforce ads businesses list [options]

OptionDescription
--connection <uuid>Owned Meta Ads connection UUID

Also accepts the common options listed at the top of this page.

smallforce ads ad-sets

Inspect, update, duplicate, and manage Meta Ads ad sets

smallforce ads ad-sets get

Get one ad set with live schedule and learning state

Usage: smallforce ads ad-sets get [options] <adSetId>

ArgumentDescription
adSetIdLocal ad-set id from campaigns tree
OptionDescription
--account <adAccountId>Local id from ads accounts list
--campaign <campaignId>Local campaign id from campaigns tree

Also accepts the common options listed at the top of this page.

Example:
  $ smallforce ads ad-sets get <adSetId> --campaign <campaignId> --account <adAccountId> --json

smallforce ads ad-sets update

Update a Meta ad set’s delivery, budget, bidding, or customer lifecycle

Usage: smallforce ads ad-sets update [options] <adSetId>

ArgumentDescription
adSetIdLocal ad-set id from campaigns tree
OptionDescription
--account <adAccountId>Local id from ads accounts list
--campaign <campaignId>Local campaign id from campaigns tree
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Update JSON fields:
  name, status, budget, schedule, bidStrategy, bidAmount, roasAverageFloor,
  dailyMinSpendTarget, lifetimeMinSpendTarget, customerLifecycle

Budget updates only work for ABO ad sets. Bid-cap and cost-cap strategies
require bidAmount; minimum-ROAS bidding requires roasAverageFloor.
Minimum spend targets reserve a share of a matching campaign budget.
customerLifecycle takes strategy (all_customers, new_customers, or
new_customers_excluding_engaged) and existingCustomerAudienceIds / engagedAudienceIds
as local references: {"$smallforce":{"kind":"audience","id":"<local UUID>"}}.

Example:
  $ smallforce ads ad-sets update <adSetId> --campaign <campaignId> --account <adAccountId> --input '{"status":"paused","budget":{"amount":25,"type":"daily"}}'

smallforce ads ad-sets list

List Meta ad sets including empty sets

Usage: smallforce ads ad-sets list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.campaignId (optional): local campaign reference
    Platform campaign ID. Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  query.adSetId (optional): local ad_set reference
    Platform ad set ID. Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  query.platform (optional): "facebook" | "instagram"
  query.status (optional): "active" | "paused" | "pending_review" | "rejected" | "completed" | "cancelled" | "error"
    Filter by the ad set's stored `status`, the value each row returns. A live read does not change it. Rows whose `status` is null match no filter.
  query.page (optional): integer
  query.limit (optional): integer

Request skeleton:
{
  "query": {
    "campaignId": {
      "$smallforce": {
        "id": "<local campaign UUID>",
        "kind": "campaign"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads ad-sets delete

Delete a Meta ad set and its ads

Usage: smallforce ads ad-sets delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local ad-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads ad-sets duplicate

Duplicate a Meta ad set

Usage: smallforce ads ad-sets duplicate [options] <targetId>

ArgumentDescription
targetIdSmallForce-local ad-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.platform (required): "facebook" | "instagram"
  body.campaignId (optional): local campaign reference
    Destination platform campaign id (defaults to the source's campaign). Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  body.deepCopy (optional): boolean
    Copy child ads + creatives
  body.statusOption (optional): "ACTIVE" | "PAUSED" | "INHERITED_FROM_SOURCE"
  body.startTime (optional): string(date-time)
    Reschedule the copy's start (ISO 8601). A value without an offset (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DDTHH:MM:SS`) is read in the ad account timezone.
  body.endTime (optional): string(date-time)
    Reschedule the copy's end, read like `startTime`; a date-only end runs to 23:59:59 local.
  body.renameStrategy (optional): "DEEP_RENAME" | "ONLY_TOP_LEVEL_RENAME" | "NO_RENAME"
    Meta's native `rename_strategy` values: - `DEEP_RENAME`: renames the copied ad set and its copied ads with `renamePrefix` / `renameSuffix`. - `ONLY_TOP_LEVEL_RENAME`: renames only the copied ad set; its ads keep their source names. -...
  body.renamePrefix (optional): string
    Text prepended to each renamed object's name.
  body.renameSuffix (optional): string
    Text appended to each renamed object's name.
  body.syncAfter (optional): boolean
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "platform": "facebook"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads ad-sets status

Update a Meta ad-set status

Usage: smallforce ads ad-sets status [options] <targetId>

ArgumentDescription
targetIdSmallForce-local ad-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.status (required): "active" | "paused"
  body.platform (required): "facebook" | "instagram"
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "status": "active",
    "platform": "facebook"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements

Inspect, update, duplicate, and manage Meta advertisements

smallforce ads advertisements update

Update an ad’s name, status, or image creative

Usage: smallforce ads advertisements update [options] <adId>

ArgumentDescription
adIdLocal advertisement id from campaigns tree
OptionDescription
--account <adAccountId>Local id from ads accounts list
--campaign <campaignId>Local campaign id
--ad-set <adSetId>Local ad-set id
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Update JSON fields:
  name, status, creative

Replacement creative shape:
  {"creative":{"assetId":"<uuid>","body":"...","callToAction":"LEARN_MORE","headline":"...","linkUrl":"https://..."}}

Post-launch creative replacement currently requires an image asset. Upload it
first with assets upload and pass the returned asset id.

Example:
  $ smallforce ads advertisements update <adId> --campaign <campaignId> --ad-set <adSetId> --account <adAccountId> --input '{"status":"paused"}'

smallforce ads advertisements list

List individual Meta advertisements

Usage: smallforce ads advertisements list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
  query.source (optional): "zernio" | "all"
    all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.
  query.status (optional): "active" | "paused" | "pending_review" | "rejected" | "completed" | "cancelled" | "error"
  query.platform (optional): "facebook" | "instagram"
  query.pageId (optional): local Facebook page or social account reference
    Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's `creative.pageId`; ads with no page signal (rare IG-only... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
  query.campaignId (optional): local campaign reference
    Platform campaign ID (filter ads within a campaign). Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  query.adSetId (optional): local ad_set reference
    Platform ad set ID (filter ads within an ad set, the /{adset_id}/ads read of an adset-centric dashboard). Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  query.platformAdId (optional): local ad reference
    Meta ad ID. Returns the ad with this platform-side ad ID. Use a SmallForce-local ad reference; raw provider IDs are rejected.
  query.effectiveObjectStoryId (optional): local social_post reference
    Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). Use to map a Business-Manager-visible post back to the Zernio ad. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  query.effectiveInstagramMediaId (optional): local social_post reference
    Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). Use to map a Business-Manager-visible IG post back to the Zernio ad. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  query.fromDate (optional): string(date)
    Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
  query.toDate (optional): string(date)
    End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.

Request skeleton:
{
  "query": {
    "limit": 50
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements duplicate

Duplicate a Meta advertisement

Usage: smallforce ads advertisements duplicate [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.adSetId (optional): local ad_set reference
    Destination platform ad set id (defaults to the source's ad set). Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  body.statusOption (optional): "ACTIVE" | "PAUSED" | "INHERITED_FROM_SOURCE"
  body.renameStrategy (optional): "DEEP_RENAME" | "ONLY_TOP_LEVEL_RENAME" | "NO_RENAME"
    Meta's native `rename_strategy` values. An ad has no copied children, so `DEEP_RENAME` and `ONLY_TOP_LEVEL_RENAME` both rename the copy with `renamePrefix` / `renameSuffix`, and `NO_RENAME` keeps the source name. With no rename option...
  body.renamePrefix (optional): string
    Text prepended to the copy's name.
  body.renameSuffix (optional): string
    Text appended to the copy's name.
  body.syncAfter (optional): boolean
  body.reuseSourceCreative (optional): boolean
    Point the copy at the source ad's creative object instead of copying it. The copy keeps the same Facebook post and Instagram media, their existing likes, comments and shares, and the full creative setup (text variations included). This...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "adSetId": {
      "$smallforce": {
        "id": "<local ad_set UUID>",
        "kind": "ad_set"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements delete

Delete a Meta advertisement

Usage: smallforce ads advertisements delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements status

Update a Meta advertisement status

Usage: smallforce ads advertisements status [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.status (required): "active" | "paused"
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "status": "active"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements boost-post

Boost a SmallForce social post with Meta Ads

Usage: smallforce ads advertisements boost-post [options] <targetId>

ArgumentDescription
targetIdSmallForce-local social-post id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--target-kind <kind>social_post (default) or instagram_post from instagram-posts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.creativeFeatures (optional): object
  body.name (required): string
  body.campaignName (optional): string
    Exact name for the campaign this boost provisions. Omitted keeps the default `<name> - Campaign`. Ignored on the Meta attach shape (`adSetId`), which creates no campaign.
  body.adSetName (optional): string
    Exact name for the ad-group level this boost provisions. Omitted keeps the default `<name> - Ad Group`. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group. Ignored on the...
  body.goal (required): "engagement" | "traffic" | "awareness" | "video_views" | "lead_generation" | "conversions" | "app_promotion"
    Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. X supports engagement, traffic, awareness, video_views, app_promotion. Reddit supports traffic, awareness, video_views, lead_generation and conversions.
  body.adSetId (optional): local ad_set reference
    Meta, or TikTok with `smartPlus: true`. Attach the boosted post to this existing ad set instead of creating a campaign. - Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400. - TikTok: the id is an... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  body.existingCampaignId (optional): local campaign reference
    The campaign keeps its own status and objective (the objective must fit `goal`). Cannot be combined with adSetId or smartPlus. On Meta use POST /v1/ads/create with existingCampaignId. Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  body.identityId (optional): local TikTok identity reference
    Must be authorized on the advertiser or the call fails naming the available ones. Use a SmallForce-local TikTok identity reference; raw provider IDs are rejected.
  body.identityType (optional): "TT_USER" | "CUSTOMIZED_USER" | "BC_AUTH_TT"
    Type of identityId; resolved from the advertiser's identity list when omitted.
  body.budgetAmount (optional): number
    Budget in whole currency units, the same flat field as POST /v1/ads/create. Required unless adSetId is set.
  body.budgetType (optional): "daily" | "lifetime"
    Goes together with budgetAmount. lifetime requires schedule.endDate.
  body.lifetimeBudgetCap (optional): number
    X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount. The line item gets both daily_budget_amount_local_micro and...
  body.budget (optional): object{amount, type}
    Alias of budgetAmount + budgetType, kept for existing callers
  body.instagramAccountId (optional): local social_account reference
    Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative. Use a SmallForce-local social_account reference; raw provider IDs are rejected.
  body.destinationType (optional): "INSTAGRAM_PROFILE" | "WEBSITE" | "ON_AD" | "MESSENGER" | "WHATSAPP" | "INSTAGRAM_DIRECT"
    Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal. A messaging callToAction selects its destination automatically; an...
  body.whatsappPhoneNumber (optional): string
    Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad.
  body.currency (optional): string
    ISO 4217 currency code matching the ad account's currency. Meta only. Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
  body.startDate (optional): string(date-time)
    Ad-set start time (ISO 8601, e.g. "2026-06-10T09:00:00Z"), mapped to the ad set's `start_time`. When omitted the ad starts delivering immediately. On Meta, TikTok, X, Pinterest and Reddit a value without an offset (`YYYY-MM-DD`,...
  body.endDate (optional): string(date-time)
    Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /v1/ads/create. Maps to the ad set's `end_time` (on X, the line item's `end_time`; X campaigns carry no flight dates). On Meta, TikTok, X, Pinterest and...
  body.schedule (optional): object
    Alias of the top-level `startDate` / `endDate`, kept for existing callers. Sending both forms with differing values is a 400.
  body.targeting (optional): object
    Same geo/demographic fields as the `TargetingSpec` used by /v1/ads/create. Geo keys (`regions`/`cities`/`zips`/`metros`) resolve via GET /v1/ads/targeting/search?dimension=geo. - Meta only: city radius and lat/lng `customLocations`....
  body.locationTargetingType (optional): object
    Written on the campaign the boost creates.
  body.rawTargeting (optional): object
    Meta only. A Meta-native targeting spec (e.g. `{ "geo_locations": { "cities": [{ "key": "...", "radius": 15, "distance_unit": "kilometer" }] } }`). Sent alone, it is forwarded unchanged. Use it for advanced fields the structured object...
  body.bidStrategy (optional): object
    Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. Meta bid strategy applied to the ad...
  body.bidAmount (optional): number
    Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. Bid cap in WHOLE currency units...
  body.roasAverageFloor (optional): number
    Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. Minimum ROAS as a decimal...
  body.platformSpecificData (optional): object
    Platform-specific options. The platform is derived from `accountId`; sending options for a different platform returns a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today. **Meta**:...
  body.tracking (optional): object
    Meta only, except `pixelId`, which also picks the Reddit pixel of the new ad group (`promotedObject.pixelId` wins when both are sent). Tracking specs (pixel, URL tags).
  body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "FINANCIAL_PRODUCTS_SERVICES" | "ISSUES_ELECTIONS_POLITICS" | "ONLINE_GAMBLING_AND_GAMING">
    Special ad category of the campaign the boost creates. Required for housing, employment, credit, or political ads. - Meta: every value. - TikTok: HOUSING, EMPLOYMENT and CREDIT, sent as the campaign's `special_industries` (TikTok...
  body.specialAdCategoryCountry (optional): array<string>
    Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).
  body.regionalRegulatedCategories (optional): array<string>
    Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
  body.regionalRegulationIdentities (optional): object
    Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on ad sets created through the API even...
  body.linkUrl (optional): string(uri)
    Website URL for non-messaging CTA buttons. Send it with `callToAction`. Omit for messaging boosts. **Meta**: adds a top-level `call_to_action` to the post-reference creative. This is what gives a `traffic` boost a clickable destination...
  body.callToAction (optional): string
    CTA button label. Non-messaging CTAs require `linkUrl`. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl. **Meta**: the CTA enum of POST /v1/ads/create plus `VIEW_INSTAGRAM_PROFILE`,...
  body.sparkAuthCode (optional): string
    Maps to `auth_code` on the creative entry of /v2/ad/create/. Without it, boosts are limited to videos owned by the same account running the ads (same-BC creators only).
  body.smartPlus (optional): boolean
    Run the Spark post in a Smart+ campaign instead of a regular one: goal `conversions` = Smart+ Web Conversions, `lead_generation` = Smart+ Lead Generation. Rejected with a 400 on other platforms. **Requires:** - `sparkAuthCode`: the...
  body.sparkPosts (optional): array<object{platformPostId, sparkAuthCode}>
    Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces `platformPostId` + `sparkAuthCode`.
  body.promoCodes (optional): array<object{discountType, discountValue}>
    Rejected with a 400 on other platforms and on Lead Generation campaigns.
  body.promotedObject (optional): object
    Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic. Required when `goal` is `conversions` (Meta also...
  body.dsaBeneficiary (optional): string
    Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
  body.dsaPayor (optional): string
    Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
  body.leadGenFormId (optional): string
    Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when `goal` is `lead_generation`; ignored for other goals. - Meta: the leadgen_forms ID (create one via POST /v1/ads/lead-forms). - LinkedIn: the adForm ID (create one...
  body.status (optional): "ACTIVE" | "PAUSED"
    Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default). PAUSED pauses only the top-most object this boost creates and switches everything below it on: - New campaign: held paused with its ad...
  body.campaignStatus (optional): "ACTIVE" | "PAUSED"
    Every platform, same semantics as POST /v1/ads/create. When omitted, it follows `status`. `ACTIVE` with `status: PAUSED` switches the campaign on and holds the new ad set paused (its ad on). Rejected with a 400 alongside `adSetId` or...
  body.adSetStatus (optional): "ACTIVE" | "PAUSED"
    Every platform, same semantics as POST /v1/ads/create. Sets the switch of the new ad set alone and overrides `status` for it. Omitted, it follows `status`. `status: PAUSED` then holds the top-most new object without a level status, only...
  body.adStatus (optional): "ACTIVE" | "PAUSED"
    Sets the switch of the new ad alone, also when attaching to an existing ad set with `adSetId` (Meta, TikTok Smart+), and overrides `status` for it. Same precedence as `adSetStatus`. A DRAFT creative is not submitted for review and...
  body.budgetLevel (optional): "adset" | "campaign"
    Meta only, same semantics as POST /v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId.
  body.attributionSpec (optional): array<object{eventType, windowDays}>
    Meta only. Ad-set attribution windows, same shape as POST /v1/ads/create. Applied on OUTCOME_SALES, OUTCOME_LEADS and OUTCOME_APP_PROMOTION campaigns (conversions, lead_conversion, lead_generation, app_promotion); other objectives keep...
  body.bodies (optional): array<string>
    Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media. Under a...
  body.retryOnServerError (optional): boolean
    Meta only (a 400 elsewhere). When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it...
  body.rehostOnInstagramVideoRejection (optional): boolean
    Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279). - First, Zernio copies the video into the ad account and retries on the original post. - Then it falls back to...
  body.smartTargeting (optional): object
    Available on Video views, Traffic, Lead generation, App install, Web conversion and Community interaction. Not available with smartPlus or when attaching to an existing ad set (adSetId). Only the flags you send are written. An unwritten...
  body.optimizationGoal (optional): string
    Ad-set optimization goal override. Meta, or TikTok with `goal: video_views`. **TikTok**: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400....
  body.metaObjective (optional): "OUTCOME_ENGAGEMENT"
    Meta only, with `goal: engagement` and without `adSetId` (400 otherwise). `OUTCOME_ENGAGEMENT` creates the campaign with objective `OUTCOME_ENGAGEMENT` and the ad set with `optimization_goal` `POST_ENGAGEMENT` (unless `optimizationGoal`...
  body.validateOnly (optional): boolean
    Meta only (facebook, instagram and Meta ads connections). Dry-runs the boost with Meta's execution_options validate_only: the campaign, ad set, creative (the post reference) and ad are checked as sent, everything PAUSED, and nothing is...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "goal": "engagement"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements analytics

Read analytics for one Meta advertisement

Usage: smallforce ads advertisements analytics [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fromDate (optional): string(date)
    Start of date range (YYYY-MM-DD). Defaults to 90 days ago.
  query.toDate (optional): string(date)
    End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
  query.breakdowns (optional): string
    Comma-separated breakdown dimensions. - **Meta**: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset. - **TikTok**: gender, age,...

Request skeleton:
{
  "query": {
    "fromDate": "2026-08-01"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements previews

Read placement previews for one Meta advertisement

Usage: smallforce ads advertisements previews [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.formats (optional): string
    Comma-separated Meta ad_format values (max 10), one preview per format. Defaults to DESKTOP_FEED_STANDARD.

Request skeleton:
{
  "query": {
    "formats": "<formats>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements media

Read fresh signed media URLs for one Meta advertisement

Usage: smallforce ads advertisements media [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements tracking-tags

Read tracking parameters for a Meta advertisement

Usage: smallforce ads advertisements tracking-tags [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements update-tracking-tags

Update tracking parameters for a Meta advertisement

Usage: smallforce ads advertisements update-tracking-tags [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.urlTags (optional): array<object{key, value}>
    Meta only. Click-URL params appended to a freshly-rebuilt creative. Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded.
  body.creative (optional): object{headline, body, callToAction, linkUrl, imageUrl}
    Meta only. OPTIONAL: omit to preserve the existing creative verbatim (default). Provide it only to rebuild the creative explicitly, or for creatives whose object_story_spec Meta strips.
  body.trackingUrlTemplate (optional): string
    Full tracking template (must contain {lpurl}).
  body.finalUrlSuffix (optional): string
    Parse-only key=value params.
  body.dynamicValueParameters (optional): object
  body.customValueParameters (optional): object
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "urlTags": [
      {
        "key": "<key>",
        "value": "<value>"
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements comments

Read comments attached to a Meta advertisement

Usage: smallforce ads advertisements comments [options] <targetId>

ArgumentDescription
targetIdSmallForce-local advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.placement (optional): "facebook" | "instagram"
    Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement.
  query.limit (optional): integer
  query.since (optional): string(date)
    Defaults to 30 days before until. Maximum window is 30 days.
  query.until (optional): string(date)
    Defaults to today in UTC.
  query.cursor (optional): string
    Pagination cursor from a previous response.

Request skeleton:
{
  "query": {
    "placement": "facebook"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads advertisements performance

Rank the ad account’s ads by spend, impressions, clicks, results or ROAS

Usage: smallforce ads advertisements performance [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fromDate (required): string(date)
    Inclusive start of the range (YYYY-MM-DD).
  query.toDate (required): string(date)
    Inclusive end of the range (YYYY-MM-DD). Max 730-day range.
  query.platform (optional): "facebook" | "instagram"
    Restrict to one platform.
  query.sortBy (optional): "spend" | "impressions" | "clicks" | "conversions" | "roas"
    Metric the ads are ranked by, highest first.
  query.limit (optional): integer
    How many ads to return.

Request skeleton:
{
  "query": {
    "fromDate": "2026-08-01",
    "toDate": "2026-08-01"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads reports

Run and retrieve asynchronous Meta Insights reports

smallforce ads reports create

Submit an asynchronous Meta Insights report

Usage: smallforce ads reports create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Required JSON fields:
  idempotencyKey
  object: { "type": "account" }
       or { "type": "campaign" | "ad_set" | "ad", "id": "<local UUID>" }

Optional report fields:
  level, fields, breakdowns, actionBreakdowns, actionAttributionWindows,
  actionReportTime, useUnifiedAttributionSetting, filtering, datePreset,
  fromDate, toDate, timeIncrement

fields, breakdowns, and actionBreakdowns are arrays. datePreset is mutually
exclusive with fromDate/toDate. timeIncrement accepts 1-90, "monthly", or
"all_days". Meta validates field, breakdown, and filter combinations.

Examples:
  $ smallforce ads reports create --account <adAccountId> --input-file report.json --json
  $ smallforce ads reports create --account <adAccountId> --input '{"idempotencyKey":"<uuid>","object":{"type":"campaign","id":"<campaignId>"},"level":"ad","fields":["ad_id","ad_name","spend","actions"],"datePreset":"last_30d","timeIncrement":1}' --json

smallforce ads reports get

Poll or page one asynchronous Meta Insights report

Usage: smallforce ads reports get [options] <reportId>

ArgumentDescription
reportIdLocal report id returned by reports create
OptionDescription
--account <adAccountId>Local id from ads accounts list
--cursor <cursor>Opaque cursor from the previous JSON page
--limit <n>Rows per completed page, 1 to 500

Also accepts the common options listed at the top of this page.

While Meta is processing, this returns status and progress. Once succeeded,
--json includes raw report rows and nextCursor. The provider report handle is
never accepted by this command.

Example:
  $ smallforce ads reports get <reportId> --account <adAccountId> --limit 500 --json

smallforce ads reports wait

Wait for an asynchronous Meta Insights report to finish

Usage: smallforce ads reports wait [options] <reportId>

ArgumentDescription
reportIdLocal report id returned by reports create
OptionDescription
--account <adAccountId>Local id from ads accounts list
--cursor <cursor>Opaque cursor from a completed report page
--limit <n>Rows per completed page, 1 to 500
--poll-interval <seconds>Polling interval, 1 to 60 (default: “3”)
--timeout <seconds>Maximum wait, 1 to 3600 (default: “300”)

Also accepts the common options listed at the top of this page.

This polls SmallForce using the local report id. A timeout does not cancel the
provider job; the JSON result sets waitTimedOut=true and can be resumed later.

Example:
  $ smallforce ads reports wait <reportId> --account <adAccountId> --limit 500 --json

smallforce ads targeting

Search Meta targeting values and estimate audience reach

Search valid Meta geographic, interest, behavior, or income targets

Usage: smallforce ads targeting search [options] <query>

ArgumentDescription
queryAudience or location search text
OptionDescription
--account <adAccountId>Local id from ads accounts list
--dimension <dimension>geo, interest, behavior, income, language, workPosition, workEmployer, or workIndustry (default: “interest”)
--geo-type <type>country, country_group, region, city, zip, metro_area, place, or neighborhood
--country <code>Two-letter country code for geo searches
--limit <n>Results to return, 1 to 100

Also accepts the common options listed at the top of this page.

Use the returned IDs/keys when constructing targeting in a campaign draft.
--geo-type and --country are only valid with --dimension geo.

Examples:
  $ smallforce ads targeting search "coffee" --account <adAccountId> --dimension interest --json
  $ smallforce ads targeting search "Detroit" --account <adAccountId> --dimension geo --geo-type city --country US --json

smallforce ads targeting estimate

Estimate reach for a complete Meta targeting spec

Usage: smallforce ads targeting estimate [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--optimization-goal <goal>Optional provider optimization goal
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

The input JSON is the targeting spec itself, not a wrapper. It may contain age,
gender, interests, behaviors, included/excluded locations, languages, or other
supported Meta targeting fields.

Examples:
  $ smallforce ads targeting estimate --account <adAccountId> --input '{"countries":["US"],"ageMin":25,"ageMax":54}'
  $ smallforce ads targeting estimate --account <adAccountId> --input-file targeting.json --json

smallforce ads targeting browse

Browse Meta’s detailed targeting categories without a keyword

Usage: smallforce ads targeting browse [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.type (optional): string
    Only the nodes of this Meta type (e.g. interests, behaviors, life_events, income), plus the organizational nodes leading to them. A type that is not in the catalog returns 400.
  query.parentNodeId (optional): string
    Only the descendants (every depth) of this organizational node, e.g. `Demographics > Financial`. A nodeId that is not an organizational node of the catalog returns 400.
  query.selectable (optional): boolean
    `true` for selectable entities only, `false` for organizational nodes only.

Request skeleton:
{
  "query": {
    "type": "<type>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads predictable-reach

Quote, reserve, inspect, and release Meta Reach & Frequency delivery

smallforce ads predictable-reach quote

Create a Meta predictable-reach quote

Usage: smallforce ads predictable-reach quote [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Quote JSON fields:
  idempotencyKey, startDate, endDate, targeting, and exactly one of
  budgetAmount or reach
Optional fields:
  frequencyCap, placements

Dates must be future ISO timestamps. A quote does not reserve inventory.

Example:
  $ smallforce ads predictable-reach quote --account <adAccountId> --input-file quote.json --json

smallforce ads predictable-reach get

Read a predictable-reach quote or reservation

Usage: smallforce ads predictable-reach get [options] <predictionId>

ArgumentDescription
predictionIdPrediction id returned by quote
OptionDescription
--account <adAccountId>Local id from ads accounts list

Also accepts the common options listed at the top of this page.

smallforce ads predictable-reach reserve

Reserve inventory for a predictable-reach quote

Usage: smallforce ads predictable-reach reserve [options] <predictionId>

ArgumentDescription
predictionIdPrediction id returned by quote
OptionDescription
--account <adAccountId>Local id from ads accounts list

Also accepts the common options listed at the top of this page.

After reservation, create the campaign with buyingType "RESERVED" and the
returned rfPredictionId. Omit budget and schedule because the reservation owns
pricing and dates.

Example:
  $ smallforce ads predictable-reach reserve <predictionId> --account <adAccountId> --json

smallforce ads predictable-reach release

Release a predictable-reach reservation

Usage: smallforce ads predictable-reach release [options] <predictionId>

ArgumentDescription
predictionIdReserved prediction id
OptionDescription
--account <adAccountId>Local id from ads accounts list

Also accepts the common options listed at the top of this page.

This releases reserved Meta inventory. Do not release a reservation that is
still intended for campaign launch.

Example:
  $ smallforce ads predictable-reach release <predictionId> --account <adAccountId>

smallforce ads lead-forms

List, create, inspect, archive, test, and read Meta Instant Forms

smallforce ads lead-forms list

List Meta Instant Forms accessible to an ad account

Usage: smallforce ads lead-forms list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--cursor <cursor>Opaque provider cursor from the previous page
--limit <n>Forms per page, 1 to 100

Also accepts the common options listed at the top of this page.

Example:
  $ smallforce ads lead-forms list --account <adAccountId> --json

smallforce ads lead-forms get

Get one Meta Instant Form

Usage: smallforce ads lead-forms get [options] <formId>

ArgumentDescription
formIdLocal form id from lead-forms list
OptionDescription
--account <adAccountId>Local id from ads accounts list

Also accepts the common options listed at the top of this page.

smallforce ads lead-forms create

Create a Meta Instant Form

Usage: smallforce ads lead-forms create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Required JSON fields:
  name, privacyPolicyUrl, questions

New Instant Form controls:
  isPhoneSmsVerifyEnabled (optional boolean)
  thankYouEnableMessenger (optional boolean)

This provider operation is not idempotent. Do not automatically retry a failed
request unless you have confirmed that Meta did not create the form.

Example:
  $ smallforce ads lead-forms create --account <adAccountId> --input-file lead-form.json --json

smallforce ads lead-forms archive

Archive one Meta Instant Form

Usage: smallforce ads lead-forms archive [options] <formId>

ArgumentDescription
formIdLocal form id from lead-forms list
OptionDescription
--account <adAccountId>Local id from ads accounts list

Also accepts the common options listed at the top of this page.

This archives the provider form; it does not merely hide a local row.

Example:
  $ smallforce ads lead-forms archive <formId> --account <adAccountId>

smallforce ads lead-forms test-lead

Create a Meta test lead for one Instant Form

Usage: smallforce ads lead-forms test-lead [options] <formId>

ArgumentDescription
formIdLocal form id from lead-forms list
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Input shape:
  {"fieldData":[{"name":"email","values":["test@example.com"]}]}

Example:
  $ smallforce ads lead-forms test-lead <formId> --account <adAccountId> --input '{"fieldData":[{"name":"email","values":["test@example.com"]}]}' --json

smallforce ads lead-forms form-leads

List leads submitted to one Meta Instant Form

Usage: smallforce ads lead-forms form-leads [options] <targetId>

ArgumentDescription
targetIdSmallForce-local lead-form id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
  query.cursor (optional): string
  query.since (optional): integer
    Unix seconds.

Request skeleton:
{
  "query": {
    "limit": 25
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads leads

Read captured Meta leads

smallforce ads leads list

List Meta leads for an advertising account

Usage: smallforce ads leads list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--form <formId>Filter by one Meta lead-form id
--since <iso>Only leads created after this ISO timestamp
--status <statuses>Only leads in these statuses, comma-separated: new, contacted, unreachable, qualified, converted, disqualified
--cursor <cursor>Opaque provider cursor from the previous page
--limit <n>Leads per page, 1 to 100

Also accepts the common options listed at the top of this page.

Track a lead toward a sale with ads leads status (the lead id is "Lead id" here).

Examples:
  $ smallforce ads leads list --account <adAccountId> --json
  $ smallforce ads leads list --account <adAccountId> --status new,contacted
  $ smallforce ads leads list --account <adAccountId> --form <formId> --since 2026-07-01T00:00:00Z --json

smallforce ads leads counts

Count stored Meta leads by status

Usage: smallforce ads leads counts [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.campaignId (optional): local campaign reference
    The platform campaign id the leads came from. Use a SmallForce-local campaign reference; raw provider IDs are rejected.

Request skeleton:
{
  "query": {
    "campaignId": {
      "$smallforce": {
        "id": "<local campaign UUID>",
        "kind": "campaign"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads leads status

Set a Meta lead’s status, and optionally its value, to track it to a sale

Usage: smallforce ads leads status [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.status (required): "new" | "contacted" | "unreachable" | "qualified" | "converted" | "disqualified"
  body.value (optional): number
    Deal value; requires currency.
  body.currency (optional): string
    ISO 4217 code.
query: no client-supplied fields
path:
  path.id (required): string
    Zernio lead id, or the Meta leadgenId (then accountId is required).

Request skeleton:
{
  "body": {
    "status": "new"
  },
  "path": {
    "id": "<lead id from ads leads list>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads account-users

Manage Meta ad-account access

smallforce ads account-users assign

Assign ad account user

Usage: smallforce ads account-users assign [options] <targetId>

ArgumentDescription
targetIdSmallForce-local meta-business-user id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.tasks (required): array<"MANAGE" | "ADVERTISE" | "ANALYZE" | "DRAFT">
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "tasks": [
      "MANAGE"
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads account-users list

List ad account users

Usage: smallforce ads account-users list [options] <targetId>

ArgumentDescription
targetIdSmallForce-local meta-business id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads account-users remove

Remove ad account user

Usage: smallforce ads account-users remove [options] <targetId>

ArgumentDescription
targetIdSmallForce-local meta-business-user id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads page-users

Manage Facebook Page access

smallforce ads page-users assign

Assign page user

Usage: smallforce ads page-users assign [options] <targetId>

ArgumentDescription
targetIdSmallForce-local facebook-page id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.businessId (required): local Meta business reference
    Business portfolio the user belongs to. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.
  body.userId (required): local meta_business_user reference
    Business-scoped user id from GET /v1/ads/businesses/users. Use a SmallForce-local meta_business_user reference; raw provider IDs are rejected.
  body.tasks (required): array<"MANAGE" | "CREATE_CONTENT" | "MODERATE" | "MESSAGING" | "ADVERTISE" | "ANALYZE">
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "businessId": {
      "$smallforce": {
        "id": "<local meta_business UUID>",
        "kind": "meta_business"
      }
    },
    "userId": {
      "$smallforce": {
        "id": "<local meta_business_user UUID>",
        "kind": "meta_business_user"
      }
    },
    "tasks": [
      "MANAGE"
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads page-users list

List page users

Usage: smallforce ads page-users list [options] <targetId>

ArgumentDescription
targetIdSmallForce-local facebook-page id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.businessId (required): local Meta business reference
    Business portfolio whose people to list. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.

Request skeleton:
{
  "query": {
    "businessId": {
      "$smallforce": {
        "id": "<local meta_business UUID>",
        "kind": "meta_business"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads page-users remove

Remove page user

Usage: smallforce ads page-users remove [options] <targetId>

ArgumentDescription
targetIdSmallForce-local facebook-page id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.userId (required): local meta_business_user reference
    Business-scoped user id. Use a SmallForce-local meta_business_user reference; raw provider IDs are rejected.

Request skeleton:
{
  "query": {
    "userId": {
      "$smallforce": {
        "id": "<local meta_business_user UUID>",
        "kind": "meta_business_user"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads videos

Manage Meta Ads videos

smallforce ads videos status

Get ad video status

Usage: smallforce ads videos status [options] <targetId>

ArgumentDescription
targetIdSmallForce-local video id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads business-users

Discover Meta business users and system users

smallforce ads business-users list

List meta business users

Usage: smallforce ads business-users list [options] <targetId>

ArgumentDescription
targetIdSmallForce-local meta-business id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads instagram-posts

Manage Meta Ads instagram-posts

smallforce ads instagram-posts list

List Instagram posts to boost

Usage: smallforce ads instagram-posts list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.igUserId (optional): local Instagram identity reference
    Instagram identity to list. Must be one this connection can reach, otherwise the request is rejected with a 400. Use a SmallForce-local Instagram identity reference; raw provider IDs are rejected.
  query.limit (optional): integer
    Number of posts to return per page.
  query.after (optional): string
    Opaque Meta cursor from a previous response's paging.after.

Request skeleton:
{
  "query": {
    "igUserId": {
      "$smallforce": {
        "id": "<local instagram_identity UUID>",
        "kind": "instagram_identity"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads test-leads

Manage Meta Ads test-leads

smallforce ads test-leads delete

Delete a test lead

Usage: smallforce ads test-leads delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local lead-form id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalogs

Manage Meta Ads catalogs

smallforce ads catalogs create

Create a Meta product catalog

Usage: smallforce ads catalogs create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.businessId (optional): local Meta business reference
    Business portfolio that owns the catalog. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.
  body.name (required): string
  body.vertical (optional): "commerce" | "adoptable_pets" | "apps_and_software" | "articles_and_publications" | "destinations" | "flights" | "generic" | "home_listings" | "hotels" | "local_service_businesses" | "media_titles" | "offer_items" | ...
    Meta catalog vertical. Use services for a professional services catalog (for example one linked to WhatsApp). local_service_business is a deprecated alias of local_service_businesses. The product endpoints under...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalogs get

Get a product catalog

Usage: smallforce ads catalogs get [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalogs delete

Delete a product catalog

Usage: smallforce ads catalogs delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-products

Manage Meta Ads catalog-products

smallforce ads catalog-products list

List a catalog’s products

Usage: smallforce ads catalog-products list [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.limit (optional): integer
  query.after (optional): string
    Cursor from the previous page's `nextCursor`
  query.retailerId (optional): string
    Only the product with this retailer id (your SKU)

Request skeleton:
{
  "query": {
    "limit": 25
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-products create

Add a product to a catalog

Usage: smallforce ads catalog-products create [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.product (required): object{retailerId, name, url, imageUrl, price, currency}
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "product": {
      "retailerId": "<retailerId>",
      "name": "Example Meta Ads resource",
      "url": "https://example.com/offer",
      "imageUrl": {
        "$smallforceAsset": "<SmallForce asset UUID>"
      },
      "price": 1,
      "currency": "USD"
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-products batch

Create, update or delete products in bulk

Usage: smallforce ads catalog-products batch [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.requests (required): array<object{method, product}>
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "requests": [
      {
        "method": "CREATE",
        "product": {
          "retailerId": "<retailerId>"
        }
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-products get

Get a product

Usage: smallforce ads catalog-products get [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-product id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-products update

Update a product

Usage: smallforce ads catalog-products update [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-product id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.product (required): object
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "product": {
      "retailerId": "<retailerId>"
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-products delete

Delete a product

Usage: smallforce ads catalog-products delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-product id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-batches

Manage Meta Ads catalog-batches

smallforce ads catalog-batches get

Get a bulk request’s status

Usage: smallforce ads catalog-batches get [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-batch id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-feeds

Manage Meta Ads catalog-feeds

smallforce ads catalog-feeds list

List a catalog’s product feeds

Usage: smallforce ads catalog-feeds list [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-feeds create

Create a product feed

Usage: smallforce ads catalog-feeds create [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
  body.schedule (optional): object{interval, url}
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-uploads

Manage Meta Ads catalog-uploads

smallforce ads catalog-uploads list

List a feed’s uploads

Usage: smallforce ads catalog-uploads list [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-feed id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-uploads create

Fetch a feed file now

Usage: smallforce ads catalog-uploads create [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-feed id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.url (required): string(uri)
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "url": "https://example.com/offer"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-sets

Manage Meta Ads catalog-sets

smallforce ads catalog-sets create

Create a product set

Usage: smallforce ads catalog-sets create [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
  body.filter (required): object
    Meta product set filter
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "filter": {}
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-sets update

Update a product set

Usage: smallforce ads catalog-sets update [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-product-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (optional): string
  body.filter (optional): object
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads catalog-sets delete

Delete a product set

Usage: smallforce ads catalog-sets delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog-product-set id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--idempotency-key <key>Idempotency key forwarded for provider mutations
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads identities

Manage Meta Ads identities

smallforce ads identities list

List Instagram ad identities

Usage: smallforce ads identities list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads applications

Manage Meta Ads applications

smallforce ads applications list

List advertisable apps

Usage: smallforce ads applications list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads applications ios-limits

Get iOS 14 campaign limits

Usage: smallforce ads applications ios-limits [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.applicationId (required): local application reference
    Meta application ID from advertisable-applications. Use a SmallForce-local application reference; raw provider IDs are rejected.

Request skeleton:
{
  "query": {
    "applicationId": {
      "$smallforce": {
        "id": "<local application UUID>",
        "kind": "application"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads partnerships

Manage Meta Ads partnerships

smallforce ads partnerships content

List partnership ad content

Usage: smallforce ads partnerships content [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.creatorUsername (optional): string
    Creator username. Required unless postUrl is supplied.
  query.postUrl (optional): string(uri)
    Instagram post permalink. Required unless creatorUsername is supplied.
  query.onlyAllowlisted (optional): boolean
    Return only creators with account-level permission.

Request skeleton:
{
  "query": {
    "creatorUsername": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads partnerships permissions

List partnership permissions

Usage: smallforce ads partnerships permissions [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.creatorUsername (optional): string
    Filter by creator username.

Request skeleton:
{
  "query": {
    "creatorUsername": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads partnerships set-permission

Set partnership permission

Usage: smallforce ads partnerships set-permission [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.creatorUsername (required): string
  body.revoke (optional): boolean
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "creatorUsername": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads insights

Run synchronous Meta advertising insights queries

smallforce ads insights query

Run a synchronous Meta Insights query

Usage: smallforce ads insights query [options] <targetId>

ArgumentDescription
targetIdSmallForce-local ad-account, campaign, ad-set, or advertisement id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--target-kind <kind>ad_account, campaign, ad_set, or ad
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.reportType (optional): "BASIC" | "AUDIENCE"
  query.dataLevel (optional): "AUCTION_ADVERTISER" | "AUCTION_CAMPAIGN" | "AUCTION_ADGROUP" | "AUCTION_AD"
  query.dimensions (optional): string
  query.metrics (optional): string
  query.page (optional): integer
  query.pageSize (optional): integer
  query.level (optional): "ad" | "adset" | "campaign" | "account"
    Row granularity
  query.fields (optional): string
    Comma-separated Graph insights fields (e.g. spend,impressions,frequency,website_purchase_roas). Omitted = Meta's default set.
  query.breakdowns (optional): string
    Meta only: comma-separated Graph breakdowns (e.g. age,gender or publisher_platform).
  query.actionBreakdowns (optional): string
    Comma-separated Graph action breakdowns; segments the actions[] arrays in each row. Pass `none` to clear Meta's default action_type breakdown, required to combine some non-action breakdowns such as instagram_ads_follow_type (otherwise...
  query.actionAttributionWindows (optional): string
    Comma-separated Meta attribution windows. Action values are returned keyed per window.
  query.actionReportTime (optional): string
    When actions are counted: impression, conversion or mixed.
  query.useUnifiedAttributionSetting (optional): boolean
    Use the ad sets' own attribution settings for action counting.
  query.filtering (optional): string
    JSON array of filter objects: [{"field", "operator", "value"}]. Applied server-side by Meta or TikTok (TikTok fields e.g. campaign_ids, adgroup_ids, ad_ids).
  query.datePreset (optional): string
    Meta date_preset (e.g. last_7d, last_30d, this_month). Mutually exclusive with fromDate/toDate.
  query.fromDate (optional): string(date)
    Start of range (YYYY-MM-DD); requires toDate.
  query.toDate (optional): string(date)
    End of range (YYYY-MM-DD); requires fromDate.
  query.timeIncrement (optional): string
    Days per row (1-90), monthly, or all_days.
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "reportType": "BASIC"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives

Manage reusable Meta creatives, images, videos, and catalogs

smallforce ads creatives list

List reusable Meta ad creatives

Usage: smallforce ads creatives list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fields (optional): string
    Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "fields": "<fields>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives create

Create a reusable Meta ad creative

Usage: smallforce ads creatives create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.headline (required): string
  body.body (required): string
    Primary text
  body.description (optional): string
    Link description below the headline; omitted = Meta scrapes the destination's OG description.
  body.callToAction (optional): string
    CTA type (same whitelist as POST /v1/ads/create).
  body.linkUrl (required): string(uri)
  body.imageUrl (optional): SmallForce asset reference
    Publicly reachable image; uploaded to the account's library server-side.
  body.imageHash (optional): local image reference
    Existing library image hash (POST /v1/ads/images or GET /v1/ads/images). Use a SmallForce-local image reference; raw provider IDs are rejected.
  body.carouselCards (optional): array<object{imageUrl, linkUrl}>
  body.instagramAccountId (optional): local social_account reference
    Meta only. The Instagram account the creative runs as, mapped to `instagram_user_id`: an id from `GET /v1/ads/instagram-accounts`, including a Page-backed one. - Given, it is never swapped. One the ad account cannot use returns 400... Use a SmallForce-local social_account reference; raw provider IDs are rejected.
  body.optimizeCardOrder (optional): boolean
    Only with `carouselCards` (a 400 without them). Sets `link_data.multi_share_optimized`: - `false`: keeps the cards in the order given. Meta then takes at most 5 cards, so `false` with more than 5 cards is a 400. - `true`: lets Meta...
  body.urlTags (optional): string
    Appended to every outbound URL (e.g. utm_source=fb).
  body.creativeFeatures (optional): object
    Meta only. Applied to each new creative, including standalone and attach shapes. With creatives[], these are defaults; an item replaces the whole feature map, including an empty map. auto_promotion_tag is an Advantage+ enhancement, not...
  body.multiAdvertiser (optional): "OPT_IN" | "OPT_OUT"
    Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta...
  body.aiDisclosure (optional): "OPT_IN" | "OPT_OUT"
    Meta only. Meta's "Ad includes media created or edited with AI" disclosure (the Ads Manager checkbox), stored on the creative as `generative_asset_spec.transparency_metadata.self_disclosure`. - OPT_IN: checks it. - OPT_OUT: explicitly...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "headline": "A useful offer",
    "body": "Learn more about this offer.",
    "linkUrl": "https://example.com/offer"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives get

Read a reusable Meta ad creative

Usage: smallforce ads creatives get [options] <targetId>

ArgumentDescription
targetIdSmallForce-local creative id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fields (optional): string
    Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
  query.thumbnailWidth (optional): integer
    Width in pixels of the `thumbnail_url` rendering, forwarded to Meta as `thumbnail_width`. Without it Meta returns a 64x64 thumbnail.
  query.thumbnailHeight (optional): integer
    Height in pixels of the `thumbnail_url` rendering, forwarded to Meta as `thumbnail_height`. Without it Meta returns a 64x64 thumbnail.

Request skeleton:
{
  "query": {
    "fields": "<fields>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives update

Update a reusable Meta ad creative

Usage: smallforce ads creatives update [options] <targetId>

ArgumentDescription
targetIdSmallForce-local creative id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives delete

Delete a reusable Meta ad creative

Usage: smallforce ads creatives delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local creative id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives upload-image

Upload a SmallForce image asset to Meta Ads

Usage: smallforce ads creatives upload-image [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--asset <assetId>SmallForce image asset id
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; supply the SmallForce asset with --asset.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives list-images

List Meta ad-account images

Usage: smallforce ads creatives list-images [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fields (optional): string
    Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "fields": "<fields>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives upload-video

Upload a SmallForce video asset to Meta Ads

Usage: smallforce ads creatives upload-video [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--asset <assetId>SmallForce video asset id
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (optional): string
    Optional video name shown in the Ads Manager media library. Takes precedence over filename.
  body.async (optional): boolean
    true: answer 202 once Meta accepts the upload instead of waiting for processing. Poll GET /v1/ads/videos/{videoId} or subscribe to ad.video.processed.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives list-videos

List Meta ad-account videos

Usage: smallforce ads creatives list-videos [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.fields (optional): string
    Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is...
  query.limit (optional): integer
    Rows per page
  query.after (optional): string
    Cursor from paging.after of the previous page.

Request skeleton:
{
  "query": {
    "fields": "<fields>"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives delete-video

Delete a Meta ad-account video

Usage: smallforce ads creatives delete-video [options] <targetId>

ArgumentDescription
targetIdSmallForce-local video id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives catalogs

List Meta commerce catalogs

Usage: smallforce ads creatives catalogs [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.businessId (optional): local Meta business reference
    Meta business portfolio ID to list. When it is omitted and the Meta login can see several portfolios, the 400 carries `details.businesses` (id + name) so a client can offer the choice. Use a SmallForce-local Meta business reference; raw provider IDs are rejected.

Request skeleton:
{
  "query": {
    "businessId": {
      "$smallforce": {
        "id": "<local meta_business UUID>",
        "kind": "meta_business"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads creatives product-sets

List product sets in a Meta catalog

Usage: smallforce ads creatives product-sets [options] <targetId>

ArgumentDescription
targetIdSmallForce-local catalog id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags

Manage Meta pixels, datasets, sharing, and statistics

smallforce ads tracking-tags list

List Meta pixels and datasets

Usage: smallforce ads tracking-tags list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags create

Create a Meta pixel

Usage: smallforce ads tracking-tags create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
  body.defaultEventType (optional): "order_created" | "lead_created" | "items_added" | "contents_viewed" | "checkout_started" | "registration_completed" | "subscription_created" | "trial_started" | "appointment_scheduled" | "page_viewed" | "app_installed" | "app_opened"
    OpenAI Ads only (ignored by Meta). When set, also provisions a standard conversion event setting wired to the new pixel, so `goal: conversions` ad creates on `POST /v1/ads/create` have an event to reference immediately.
  body.automaticMatchingFields (optional): array<"em" | "ph" | "fn" | "ln" | "ge" | "db" | "ct" | "st" | "zp" | "country" | "external_id">
    Customer data the new tag matches automatically (automatic enhanced match): `em` email, `ph` phone, `fn`/`ln` name, `ge` gender, `db` date of birth, `ct`/`st`/`zp`/`country` location, `external_id`.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags get

Read a Meta pixel

Usage: smallforce ads tracking-tags get [options] <targetId>

ArgumentDescription
targetIdSmallForce-local tracking-tag id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags update

Update a Meta pixel

Usage: smallforce ads tracking-tags update [options] <targetId>

ArgumentDescription
targetIdSmallForce-local tracking-tag id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (optional): string
  body.enableAutomaticMatching (optional): boolean
    Meta Advanced Matching toggle (`enable_automatic_matching`).
  body.automaticMatchingFields (optional): array<"em" | "ph" | "fn" | "ln" | "ge" | "db" | "ct" | "st" | "zp" | "country" | "external_id">
    Which user fields Advanced Matching may collect. Meta's terse codes: em=email, ph=phone, fn=first name, ln=last name, ge=gender, db=date of birth, ct=city, st=state, zp=zip.
  body.firstPartyCookieStatus (optional): "empty" | "first_party_cookie_disabled" | "first_party_cookie_enabled"
  body.dataUseSetting (optional): "advertising_and_analytics" | "analytics_only" | "empty"
  body.enableFirstPartyCookies (optional): boolean
    Platform-neutral alternative to `firstPartyCookieStatus`.
  body.autoTagging (optional): boolean
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags shared-accounts

List ad accounts sharing a Meta pixel

Usage: smallforce ads tracking-tags shared-accounts [options] <targetId>

ArgumentDescription
targetIdSmallForce-local tracking-tag id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags share

Share a Meta pixel with another local ad account

Usage: smallforce ads tracking-tags share [options] <targetId>

ArgumentDescription
targetIdSmallForce-local tracking-tag id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.adAccountId (required): local ad_account reference
    Ad account to share with. Use a SmallForce-local ad_account reference; raw provider IDs are rejected.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "adAccountId": {
      "$smallforce": {
        "id": "<local ad_account UUID>",
        "kind": "ad_account"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags unshare

Remove a Meta pixel from another local ad account

Usage: smallforce ads tracking-tags unshare [options] <targetId>

ArgumentDescription
targetIdSmallForce-local tracking-tag id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.adAccountId (optional): local ad_account reference
    Ad account to unshare May also be sent in the JSON body. Use a SmallForce-local ad_account reference; raw provider IDs are rejected.

Request skeleton:
{
  "query": {
    "adAccountId": {
      "$smallforce": {
        "id": "<local ad_account UUID>",
        "kind": "ad_account"
      }
    }
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads tracking-tags stats

Read Meta pixel event statistics

Usage: smallforce ads tracking-tags stats [options] <targetId>

ArgumentDescription
targetIdSmallForce-local tracking-tag id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.aggregation (optional): "event" | "host" | "url" | "url_by_rule" | "pixel_fire" | "device_type" | "device_os" | "browser_type" | "had_pii" | "custom_data_field" | "match_keys" | "event_source" | ...
    Meta only (400 on other platforms): aggregation dimension. Defaults to `event`.
  query.startTime (optional): integer
    Unix seconds lower bound.
  query.endTime (optional): integer
    Unix seconds upper bound.

Request skeleton:
{
  "query": {
    "aggregation": "event"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences

Manage Meta custom audiences

smallforce ads audiences list

List Meta custom audiences

Usage: smallforce ads audiences list [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query:
  query.platform (optional): "facebook" | "instagram"
  query.type (optional): "customer_list" | "meta_engagement" | "website" | "lookalike" | "saved_targeting"
    Filter to one audience type. `saved_targeting` returns stored TargetingSpec audiences and needs no adAccountId; the other types keep only the platform audiences of that type (an empty list when the platform has none). Meta ENGAGEMENT...

Request skeleton:
{
  "query": {
    "platform": "facebook"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences create

Create a Meta custom audience

Usage: smallforce ads audiences create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (required): string
  body.description (optional): string
  body.type (required): "customer_list" | "meta_engagement" | "website" | "lookalike" | "saved_targeting"
  body.pixelId (optional): local tracking_tag reference
    website: the Meta pixel, TikTok pixel, Pinterest tag or Reddit pixel id. Use a SmallForce-local tracking_tag reference; raw provider IDs are rejected.
  body.retentionDays (optional): integer
    Required for website (Meta max 180, TikTok 7/14/30/60/90/180, Reddit max 90, Pinterest and Google max 540), meta_engagement (max 365) and tiktok_engagement (7/14/30/60/90/180; organic and live video and most business-account events only...
  body.engagementSource (optional): "page" | "instagram" | "video"
    Required for meta_engagement audiences (Meta only): what people engaged with. `page` = a Facebook Page, `instagram` = an IG professional account, `video` = a video.
  body.sourceId (optional): local social_account or video reference
    Required for meta_engagement: the Page / IG account / video id. Use a SmallForce-local social_account or video reference; raw provider IDs are rejected.
  body.event (optional): string
    The event to match. Its meaning depends on the type: - meta_engagement: the engagement event. Defaults per source (page → page_engaged, instagram → ig_business_profile_all, video → video_watched). An unknown value is a 400 that lists...
  body.sourceAudienceId (optional): local audience reference
    Required for lookalike audiences. Use a SmallForce-local audience reference; raw provider IDs are rejected.
  body.country (optional): string
    2-letter code, required for lookalike audiences
  body.ratio (optional): number
    lookalike on Meta (0.01-0.20) and Pinterest (0.01-0.10, whole percents).
  body.size (optional): "narrow" | "balanced" | "broad"
    Rejected on Meta and Pinterest.
  body.source (optional): "ads" | "organic_video" | "live_video" | "business_account"
  body.campaignIds (optional): local campaign reference[]
    Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  body.adIds (optional): local ad reference[]
    Use a SmallForce-local ad reference; raw provider IDs are rejected.
  body.urlContains (optional): string
    website on Meta, TikTok and Google. Narrows the audience from all visitors to visitors of URLs containing this substring. Ignored when `rule` is supplied.
  body.rule (optional): object
    Meta only (a 400 elsewhere). Optional raw Meta rule, replacing the one we build. Omit it for all visitors of `pixelId`, or use `urlContains` for the common page-match case. **For `website`** this is Meta's Flexible Audience Rule and is...
  body.customerFileSource (optional): string
    Data source declaration for GDPR compliance (customer_list only)
  body.spec (conditional): object
    The targeting spec to store.
query: no client-supplied fields

Body variants:
  - UploadedOrDerivedAudience (required: name, type): customer_list, website, lookalike or engagement audience (uploaded or derived from a source).
  - SavedTargetingAudience (required: type, name, spec): A reusable, stored TargetingSpec. No member upload step, no adAccountId, the spec is the audience. Reference it later via `savedTargetingId` on POST /v1/ads/create.

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "type": "customer_list"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences get

Read a Meta custom audience

Usage: smallforce ads audiences get [options] <targetId>

ArgumentDescription
targetIdSmallForce-local audience id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences update

Update a Meta custom audience

Usage: smallforce ads audiences update [options] <targetId>

ArgumentDescription
targetIdSmallForce-local audience id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.name (optional): string
  body.description (optional): string
  body.spec (optional): object
    Full replacement for the stored targeting spec.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences delete

Delete a Meta custom audience

Usage: smallforce ads audiences delete [options] <targetId>

ArgumentDescription
targetIdSmallForce-local audience id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences add-users

Add hashed customer records to a Meta custom audience

Usage: smallforce ads audiences add-users [options] <targetId>

ArgumentDescription
targetIdSmallForce-local audience id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.users (required): array<object>
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "users": [
      {
        "email": "<email>"
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads audiences remove-users

Remove hashed customer records from a Meta custom audience

Usage: smallforce ads audiences remove-users [options] <targetId>

ArgumentDescription
targetIdSmallForce-local audience id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.users (required): array<object>
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "users": [
      {
        "email": "<email>"
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads conversions

Inspect conversion quality and send Meta conversion events

smallforce ads conversions quality

Read Meta conversion match quality

Usage: smallforce ads conversions quality [options] <targetId>

ArgumentDescription
targetIdSmallForce-local conversion-destination id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads conversions send

Send conversion events to Meta

Usage: smallforce ads conversions send [options] <targetId>

ArgumentDescription
targetIdSmallForce-local conversion-destination id; raw Meta ids are rejected
OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.events (required): array<object{eventName, eventTime, eventId, user}>
  body.testCode (optional): string
    Test event code. Send it at the request root, never inside an event. A root-level `test_event_code` (Meta's own name) is accepted as an alias and must be a non-empty string; sending both with different values is a 400. - Meta: sent as...
  body.consent (optional): object
    Batch-level user consent. Required by Google for EEA/UK events under the Feb 2026 restrictions. - **Meta:** any DENIED flag enables Limited Data Use on every event in the batch (data_processing_options ["LDU"] with geolocation, country...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "events": [
      {
        "eventName": "Purchase",
        "eventTime": 1788134400,
        "eventId": "evt-001",
        "user": {
          "email": "<email>"
        }
      }
    ]
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads conversions destinations

List Meta conversion destinations

Usage: smallforce ads conversions destinations [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body: no client-supplied fields
query: no client-supplied fields

No provider JSON is required; omit --input and --input-file.

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads messaging

Create Meta messaging, call, and WhatsApp advertisements

smallforce ads messaging create

Create a Meta messaging advertisement

Usage: smallforce ads messaging create [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.retryOnServerError (optional): boolean
    When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`. `false`...
  body.creativeFeatures (optional): object
    Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.
  body.tracking (optional): object
  body.name (required): string
    Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
  body.campaignName (optional): string
    Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
  body.adSetName (optional): string
    Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
  body.platformPostId (optional): local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference
    Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. - Facebook IDs become object_story_id. - Instagram IDs become... Use a SmallForce-local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference; raw provider IDs are rejected.
  body.existingPostId (optional): local social_post reference
    Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  body.objectStoryId (optional): local social_post reference
    Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  body.pageId (optional): local Facebook page or social account reference
    Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
  body.whatsappPhoneNumber (optional): string
    WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. - Sent to the creative CTA and, when creating a new ad set, its promoted_object. - Meta can accept the number yet...
  body.headline (optional): string
    Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.
  body.body (optional): string
    Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
  body.description (optional): string
    Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. Meta shows it mainly on Facebook Feed placements,...
  body.imageUrl (optional): SmallForce asset reference
    Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.
  body.video (optional): object
    Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
  body.welcomeMessage (optional): object{text}
    Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
  body.carouselCards (optional): array<object{imageUrl}>
    Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. - Meta may reorder cards for performance, since `multi_share_optimized`...
  body.optimizeCardOrder (optional): boolean
    Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. - `false`: keeps the cards in the order given. Meta then takes at most 5...
  body.creatives (optional): array<object>
    Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId...
  body.adSetId (optional): local ad_set reference
    Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. The ad set then owns budget, targeting and... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  body.existingCampaignId (optional): local campaign reference
    Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. - The campaign's objective... Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  body.budgetLevel (optional): "adset" | "campaign"
    Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not...
  body.budgetAmount (optional): number
    Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.
  body.budgetType (optional): "daily" | "lifetime"
    Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.
  body.currency (optional): string
    ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
  body.startDate (optional): string
    When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used as is; one without an offset (`2027-01-15T10:00:00`) is read in the ad account's timezone, and a...
  body.endDate (optional): string
    ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.
  body.countries (optional): array<string>
    ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
  body.cities (optional): array<object{key}>
    City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km /...
  body.regions (optional): array<object{key}>
    Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
  body.zips (optional): array<object{key}>
    ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
  body.metros (optional): array<object{key}>
    DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
  body.countryGroups (optional): array<"africa" | "asia" | "europe" | "north_america" | "south_america" | "oceania" | "central_america" | "caribbean" | "eea" | "euro_area" | "nafta" | "mercosur" | ...>
    Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`....
  body.customLocations (optional): array<object{latitude, longitude, radius, distanceUnit}>
    Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
  body.ageMin (optional): integer
  body.ageMax (optional): integer
  body.interests (optional): array<object{id}>
  body.audienceId (optional): local audience reference
    Custom audience ID to target. Use a SmallForce-local audience reference; raw provider IDs are rejected.
  body.placements (optional): object
    Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,...
  body.gender (optional): "all" | "male" | "female"
    Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.
  body.languages (optional): array<string>
    Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"). Meta numeric locale ids (e.g. "24" for English UK) are also...
  body.places (optional): array<object{key}>
    Meta place keys (from GET /v1/ads/targeting/search).
  body.neighborhoods (optional): array<object{key}>
    Meta neighborhood keys (from GET /v1/ads/targeting/search).
  body.excludedLocations (optional): object
    Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
  body.behaviors (optional): array<object{id}>
    Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across).
  body.workPositions (optional): array<object{id}>
  body.workEmployers (optional): array<object{id}>
  body.workIndustries (optional): array<object{id}>
  body.incomeTier (optional): "top_5" | "top_10" | "top_10_25" | "top_25_50"
    Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
  body.userOs (optional): array<string>
    Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"].
  body.userDevice (optional): array<string>
    Meta `user_device`.
  body.audienceInclude (optional): array<string>
    Custom or lookalike audience ids to include.
  body.audienceExclude (optional): array<string>
    Custom or lookalike audience ids to exclude.
  body.savedTargetingId (optional): string
    ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields.
  body.targeting (optional): object
    Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.
  body.rawTargeting (optional): object
    Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one...
  body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
    Meta special ad categories on the new campaign.
  body.specialAdCategoryCountry (optional): array<string>
    Countries the special ad category applies to. Requires specialAdCategories.
  body.advantageAudience (optional): 0 | 1
    Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
  body.objective (optional): "OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"
    Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
  body.status (optional): "ACTIVE" | "PAUSED"
    Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.
  body.campaignStatus (optional): "ACTIVE" | "PAUSED"
    Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`. - `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). - `ACTIVE` with `status:...
  body.adSetStatus (optional): "ACTIVE" | "PAUSED"
    Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED`...
  body.adStatus (optional): "ACTIVE" | "PAUSED"
    Ad-level status, same semantics as `POST /v1/ads/create`. Sets the new ads' switch and overrides `status` for them, also with `adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all PAUSED to create every object paused.
  body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
    Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`....
  body.bidAmount (optional): number
    Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.
  body.roasAverageFloor (optional): number
    Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.
  body.dsaBeneficiary (optional): string
    Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
  body.dsaPayor (optional): string
    Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
  body.regionalRegulatedCategories (optional): array<string>
    Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
  body.regionalRegulationIdentities (optional): object
    Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on API-created ad sets even when a default...
  body.destination (optional): "whatsapp" | "messenger" | "instagram_direct"
    Where the conversation opens when the ad is tapped. Set this OR `destinations`, not both.
  body.destinations (optional): array<"whatsapp" | "messenger" | "instagram_direct">
    Two or three messaging apps on ONE ad set, like Ads Manager's "all messaging apps". Set this OR `destination`, not both. The ad set gets Meta's combined destination_type (e.g. MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP) and the...
  body.placementAssets (optional): object{rules}
    A different image or video per placement on one messaging ad, e.g. a 4:5 image on Feed and a 9:16 image on Stories/Reels. Works on the single-creative shape and on attach (`adSetId`). Replaces top-level `imageUrl` / `video` (sending...
  body.validateOnly (optional): boolean
    Dry-runs the ad on Meta with execution_options validate_only, as ONE inline campaign + ad set + creative + ad (or creative + ad on the existing ad set with `adSetId`). Nothing is uploaded, created or stored; media is checked by URL. -...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads messaging call

Create a Meta call advertisement

Usage: smallforce ads messaging call [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.retryOnServerError (optional): boolean
    When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`. `false`...
  body.creativeFeatures (optional): object
    Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.
  body.tracking (optional): object
  body.name (required): string
    Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
  body.campaignName (optional): string
    Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
  body.adSetName (optional): string
    Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
  body.platformPostId (optional): local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference
    Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. - Facebook IDs become object_story_id. - Instagram IDs become... Use a SmallForce-local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference; raw provider IDs are rejected.
  body.existingPostId (optional): local social_post reference
    Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  body.objectStoryId (optional): local social_post reference
    Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  body.pageId (optional): local Facebook page or social account reference
    Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
  body.whatsappPhoneNumber (optional): string
    WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. - Sent to the creative CTA and, when creating a new ad set, its promoted_object. - Meta can accept the number yet...
  body.headline (optional): string
    Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.
  body.body (optional): string
    Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
  body.description (optional): string
    Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. Meta shows it mainly on Facebook Feed placements,...
  body.imageUrl (optional): SmallForce asset reference
    Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.
  body.video (optional): object
    Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
  body.welcomeMessage (optional): object{text}
    Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
  body.carouselCards (optional): array<object{imageUrl}>
    Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. - Meta may reorder cards for performance, since `multi_share_optimized`...
  body.optimizeCardOrder (optional): boolean
    Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. - `false`: keeps the cards in the order given. Meta then takes at most 5...
  body.creatives (optional): array<object>
    Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId...
  body.adSetId (optional): local ad_set reference
    Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. The ad set then owns budget, targeting and... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  body.existingCampaignId (optional): local campaign reference
    Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. - The campaign's objective... Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  body.budgetLevel (optional): "adset" | "campaign"
    Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not...
  body.budgetAmount (optional): number
    Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.
  body.budgetType (optional): "daily" | "lifetime"
    Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.
  body.currency (optional): string
    ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
  body.startDate (optional): string
    When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used as is; one without an offset (`2027-01-15T10:00:00`) is read in the ad account's timezone, and a...
  body.endDate (optional): string
    ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.
  body.countries (optional): array<string>
    ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
  body.cities (optional): array<object{key}>
    City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km /...
  body.regions (optional): array<object{key}>
    Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
  body.zips (optional): array<object{key}>
    ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
  body.metros (optional): array<object{key}>
    DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
  body.countryGroups (optional): array<"africa" | "asia" | "europe" | "north_america" | "south_america" | "oceania" | "central_america" | "caribbean" | "eea" | "euro_area" | "nafta" | "mercosur" | ...>
    Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`....
  body.customLocations (optional): array<object{latitude, longitude, radius, distanceUnit}>
    Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
  body.ageMin (optional): integer
  body.ageMax (optional): integer
  body.interests (optional): array<object{id}>
  body.audienceId (optional): local audience reference
    Custom audience ID to target. Use a SmallForce-local audience reference; raw provider IDs are rejected.
  body.placements (optional): object
    Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,...
  body.gender (optional): "all" | "male" | "female"
    Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.
  body.languages (optional): array<string>
    Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"). Meta numeric locale ids (e.g. "24" for English UK) are also...
  body.places (optional): array<object{key}>
    Meta place keys (from GET /v1/ads/targeting/search).
  body.neighborhoods (optional): array<object{key}>
    Meta neighborhood keys (from GET /v1/ads/targeting/search).
  body.excludedLocations (optional): object
    Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
  body.behaviors (optional): array<object{id}>
    Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across).
  body.workPositions (optional): array<object{id}>
  body.workEmployers (optional): array<object{id}>
  body.workIndustries (optional): array<object{id}>
  body.incomeTier (optional): "top_5" | "top_10" | "top_10_25" | "top_25_50"
    Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
  body.userOs (optional): array<string>
    Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"].
  body.userDevice (optional): array<string>
    Meta `user_device`.
  body.audienceInclude (optional): array<string>
    Custom or lookalike audience ids to include.
  body.audienceExclude (optional): array<string>
    Custom or lookalike audience ids to exclude.
  body.savedTargetingId (optional): string
    ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields.
  body.targeting (optional): object
    Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.
  body.rawTargeting (optional): object
    Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one...
  body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
    Meta special ad categories on the new campaign.
  body.specialAdCategoryCountry (optional): array<string>
    Countries the special ad category applies to. Requires specialAdCategories.
  body.advantageAudience (optional): 0 | 1
    Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
  body.objective (optional): "OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"
    Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
  body.status (optional): "ACTIVE" | "PAUSED"
    Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.
  body.campaignStatus (optional): "ACTIVE" | "PAUSED"
    Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`. - `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). - `ACTIVE` with `status:...
  body.adSetStatus (optional): "ACTIVE" | "PAUSED"
    Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED`...
  body.adStatus (optional): "ACTIVE" | "PAUSED"
    Ad-level status, same semantics as `POST /v1/ads/create`. Sets the new ads' switch and overrides `status` for them, also with `adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all PAUSED to create every object paused.
  body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
    Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`....
  body.bidAmount (optional): number
    Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.
  body.roasAverageFloor (optional): number
    Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.
  body.dsaBeneficiary (optional): string
    Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
  body.dsaPayor (optional): string
    Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
  body.regionalRegulatedCategories (optional): array<string>
    Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
  body.regionalRegulationIdentities (optional): object
    Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on API-created ad sets even when a default...
  body.phoneNumber (required): string
    E.164 number the CALL_NOW CTA dials (e.g. +34600111222).
  body.linkUrl (required): string(uri)
    Website shown as the creative's link. Required: Meta rejects tel: as link_data.link; the phone number rides only the CTA.
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource",
    "phoneNumber": "<phoneNumber>",
    "linkUrl": "https://example.com/offer"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads messaging whatsapp

Create a click-to-WhatsApp advertisement

Usage: smallforce ads messaging whatsapp [options]

OptionDescription
--account <adAccountId>Local id from ads accounts list
--input <json>Inline JSON request object
--input-file <path>JSON request file; use - to read from stdin

Also accepts the common options listed at the top of this page.

Provider parameters (--input or --input-file):
body:
  body.retryOnServerError (optional): boolean
    When Meta answers a create with a 5xx and reading the parent back by name finds no such object, Zernio sends the create again (at most 3 POSTs per object, never for an object created ACTIVE) and reports it in `recoveredWrites`. `false`...
  body.creativeFeatures (optional): object
    Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.
  body.tracking (optional): object
  body.name (required): string
    Ad display name. Used to derive campaign / ad set names. On the multi-creative shape, each ad's Meta name gets a " #N" suffix (1-indexed) so Ads Manager shows them as a numbered batch.
  body.campaignName (optional): string
    Exact name for the campaign this request provisions. Omitted keeps `<name> - Campaign`. Ignored with `adSetId` (the ad set already has a campaign).
  body.adSetName (optional): string
    Exact name for the ad set this request provisions. Omitted keeps `<name> - Ad Set`. Ignored with `adSetId`.
  body.platformPostId (optional): local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference
    Messaging and CTWA only. Platform post or reel ID, the same input boostPost takes as platformPostId. Mutually exclusive with objectStoryId and fresh creative fields. - Facebook IDs become object_story_id. - Instagram IDs become... Use a SmallForce-local published social post or discovered Instagram post (Spark arrays use native post IDs plus creator authorization) reference; raw provider IDs are rejected.
  body.existingPostId (optional): local social_post reference
    Alias of platformPostId, kept for existing callers. Sending both with different values is a 400. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  body.objectStoryId (optional): local social_post reference
    Messaging and CTWA only. Raw Facebook pageId_postId reference, used as object_story_id even with an Instagram account. Mutually exclusive with platformPostId and fresh creative fields. Use a SmallForce-local social_post reference; raw provider IDs are rejected.
  body.pageId (optional): local Facebook page or social account reference
    Facebook Page the ad runs as, when the connection was granted several Pages. Defaults to the Page bound to the connection. Any Page granted to the connection is accepted; other ids answer 400 listing the granted Pages. Same semantics as... Use a SmallForce-local Facebook page or social account reference; raw provider IDs are rejected.
  body.whatsappPhoneNumber (optional): string
    WhatsApp only. Optional E.164 number already paired with the Facebook Page. Omit to let Meta select the paired number. - Sent to the creative CTA and, when creating a new ad set, its promoted_object. - Meta can accept the number yet...
  body.headline (optional): string
    Single-creative shape only. Mutually exclusive with `creatives[]`. Required on a single image or video ad (including one built with `placementAssets`); not used by a `carouselCards` ad and not accepted with an existing post reference.
  body.body (optional): string
    Primary text shown above the image / video. Single-creative shape only. Mutually exclusive with `creatives[]`.
  body.description (optional): string
    Link description, independent of `headline` and `body`: Meta's `link_data.description`, `video_data.link_description` on video, and the shared description of a `placementAssets` feed. Meta shows it mainly on Facebook Feed placements,...
  body.imageUrl (optional): SmallForce asset reference
    Image asset for single-creative shape. Mutually exclusive with `video` and with `creatives[]`. Required on the single-creative shape if neither `video` nor an existing post reference is supplied.
  body.video (optional): object
    Video creative for single-creative shape. Mutually exclusive with `imageUrl` and with `creatives[]`. Required on the single-creative shape if neither `imageUrl` nor an existing post reference is supplied.
  body.welcomeMessage (optional): object{text}
    Custom chat welcome message (Meta's `page_welcome_message`, "Mensaje de bienvenida" / "Mensaje predefinido" in Ads Manager). Single-creative shape only; for `creatives[]` set it per entry.
  body.carouselCards (optional): array<object{imageUrl}>
    Messaging and CTWA only (a 400 on POST /v1/ads/call). A hand-built carousel of 2-10 image cards, sent to Meta in the given order as `link_data.child_attachments`. - Meta may reorder cards for performance, since `multi_share_optimized`...
  body.optimizeCardOrder (optional): boolean
    Only with `carouselCards` (a 400 without them). Single-creative shape; for `creatives[]` set it per entry. Sets the creative's `link_data.multi_share_optimized`. - `false`: keeps the cards in the order given. Meta then takes at most 5...
  body.creatives (optional): array<object>
    Multi-creative shape: N CTWA ads under one campaign + one ad set, sharing budget and targeting. Fresh and existing creatives can be mixed. Each entry supplies headline, body, and image/video, or a platformPostId or objectStoryId...
  body.adSetId (optional): local ad_set reference
    Attaches the creatives to this EXISTING messaging ad set instead of building a campaign, so the ad set keeps its learning phase. Its `destination_type` must match the ad's destination. The ad set then owns budget, targeting and... Use a SmallForce-local ad_set reference; raw provider IDs are rejected.
  body.existingCampaignId (optional): local campaign reference
    Creates the new messaging ad set (and its ads) under this EXISTING Meta campaign instead of a new one, e.g. several audience ad sets under one campaign. To add ads to an existing ad set instead, use `adSetId`. - The campaign's objective... Use a SmallForce-local campaign reference; raw provider IDs are rejected.
  body.budgetLevel (optional): "adset" | "campaign"
    Where the budget lives. `adset` (default) puts it on the new ad set. `campaign` creates an Advantage campaign budget (CBO): the budget and bid strategy sit on the campaign and the ad set inherits them, same as POST /v1/ads/create. Not...
  body.budgetAmount (optional): number
    Budget amount in the ad account's currency major units (e.g. dollars for USD, not cents). Must be > 0. Required unless `adSetId` is set (the ad set owns it) or `existingCampaignId` names a campaign with a campaign budget.
  body.budgetType (optional): "daily" | "lifetime"
    Required unless `adSetId` is set or `existingCampaignId` names a campaign with a campaign budget. `lifetime` requires `endDate`.
  body.currency (optional): string
    ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta...
  body.startDate (optional): string
    When the ad set starts delivering. ISO 8601 date or date-time. A value with an offset (`2027-01-15T10:00:00+01:00`, `...Z`) is used as is; one without an offset (`2027-01-15T10:00:00`) is read in the ad account's timezone, and a...
  body.endDate (optional): string
    ISO 8601 date or date-time, read like `startDate`; a date-only value ends at 23:59:59 local. Required when `budgetType` is `lifetime`.
  body.countries (optional): array<string>
    ISO 3166-1 alpha-2 country codes. Defaults to `["US"]` only when no other geo (`cities`, `regions`, `zips`, `metros`, `customLocations`) is supplied.
  body.cities (optional): array<object{key}>
    City-level geo targeting for local CTWA campaigns. Each entry maps to Meta's TargetingGeoLocationCity; `key` is Meta's city ID. `radius` and `distance_unit` are coupled: set both or neither. Meta enforces a minimum city radius (~17 km /...
  body.regions (optional): array<object{key}>
    Region / state-level geo targeting. `key` is Meta's region ID (lookupable via GET /v1/ads/targeting/search?type=region).
  body.zips (optional): array<object{key}>
    ZIP / postal-code geo targeting. `key` is the platform's postal id resolved via /v1/ads/targeting/search.
  body.metros (optional): array<object{key}>
    DMA / metro-area geo targeting. `key` is Meta's metro id (e.g. `DMA:807`).
  body.countryGroups (optional): array<"africa" | "asia" | "europe" | "north_america" | "south_america" | "oceania" | "central_america" | "caribbean" | "eea" | "euro_area" | "nafta" | "mercosur" | ...>
    Meta only. Continents and trade blocs (`geo_locations.country_groups`), for targeting a whole region without listing its countries. Combines with `countries` rather than replacing it, and is also accepted under `excludedLocations`....
  body.customLocations (optional): array<object{latitude, longitude, radius, distanceUnit}>
    Point-radius geo (Meta `geo_locations.custom_locations`). Use for targeting a radius around a specific lat/long when no Meta city/region key fits. `distanceUnit` is required.
  body.ageMin (optional): integer
  body.ageMax (optional): integer
  body.interests (optional): array<object{id}>
  body.audienceId (optional): local audience reference
    Custom audience ID to target. Use a SmallForce-local audience reference; raw provider IDs are rejected.
  body.placements (optional): object
    Manual ad placements on the shared ad set. Omit for automatic placements. When set, restricts delivery to the chosen surfaces, mapped onto the ad set's `targeting.{publisher_platforms, facebook_positions, instagram_positions,...
  body.gender (optional): "all" | "male" | "female"
    Restrict the audience by gender (Meta `genders`). Omit or send all for everyone; all is ignored in adSetId attach mode. Stored on the ad and read back in `targeting.gender`.
  body.languages (optional): array<string>
    Audience languages (Meta `locales`). A bare ISO 639-1 code targets all regional variants ("en" = all English), a region-qualified code a specific one ("en_GB", "pt_BR"). Meta numeric locale ids (e.g. "24" for English UK) are also...
  body.places (optional): array<object{key}>
    Meta place keys (from GET /v1/ads/targeting/search).
  body.neighborhoods (optional): array<object{key}>
    Meta neighborhood keys (from GET /v1/ads/targeting/search).
  body.excludedLocations (optional): object
    Geo to exclude, same shape as POST /v1/ads/create (countries, countryGroups, regions, cities, zips, places, neighborhoods, customLocations).
  body.behaviors (optional): array<object{id}>
    Behavior ids from /v1/ads/targeting/search?dimension=behavior. Meta: each dimension is its own flexible_spec entry (OR within, AND across).
  body.workPositions (optional): array<object{id}>
  body.workEmployers (optional): array<object{id}>
  body.workIndustries (optional): array<object{id}>
  body.incomeTier (optional): "top_5" | "top_10" | "top_10_25" | "top_25_50"
    Normalized household-income tier, same as POST /v1/ads/create. Incompatible with housing, employment and credit specialAdCategories.
  body.userOs (optional): array<string>
    Meta `user_os`, e.g. ["iOS_ver_14.0_and_above"].
  body.userDevice (optional): array<string>
    Meta `user_device`.
  body.audienceInclude (optional): array<string>
    Custom or lookalike audience ids to include.
  body.audienceExclude (optional): array<string>
    Custom or lookalike audience ids to exclude.
  body.savedTargetingId (optional): string
    ID of a saved_targeting audience (POST /v1/ads/audiences), expanded as the base targeting. Precedence: savedTargetingId, then `targeting`, then the flat fields.
  body.targeting (optional): object
    Nested targeting object, same contract as POST /v1/ads/create and boost. Flat fields win per key.
  body.rawTargeting (optional): object
    Meta targeting spec sent as the BASE layer of the ad set's `targeting`, exactly as POST /v1/ads/create does. Use it for anything the flat fields cannot express, such as a layered `flexible_spec` (entries AND together, ids inside one...
  body.specialAdCategories (optional): array<"HOUSING" | "EMPLOYMENT" | "CREDIT" | "ISSUES_ELECTIONS_POLITICS" | "FINANCIAL_PRODUCTS_SERVICES" | "ONLINE_GAMBLING_AND_GAMING">
    Meta special ad categories on the new campaign.
  body.specialAdCategoryCountry (optional): array<string>
    Countries the special ad category applies to. Requires specialAdCategories.
  body.advantageAudience (optional): 0 | 1
    Meta's Advantage+ audience expansion. `0` (default) keeps targeting strict; `1` lets Meta expand beyond the supplied targeting when its delivery system finds better matches. Always sent on CREATE (Meta requires it).
  body.objective (optional): "OUTCOME_ENGAGEMENT" | "OUTCOME_SALES" | "OUTCOME_LEADS"
    Defaults to `OUTCOME_ENGAGEMENT`. `OUTCOME_SALES` and `OUTCOME_LEADS` require additional account configuration (Dataset linked to the WABA for sales) and may be rejected by Meta if missing.
  body.status (optional): "ACTIVE" | "PAUSED"
    Defaults to `ACTIVE`. `PAUSED` pauses only the top-most object this call creates: the new campaign (ad set and ads switched on), or, with `adSetId`, the new ads themselves.
  body.campaignStatus (optional): "ACTIVE" | "PAUSED"
    Campaign-level status, same semantics as `POST /v1/ads/create`. Defaults to `status`. - `PAUSED`: holds the new campaign off while the ad set and ads switch on (one resume call brings the whole hierarchy live). - `ACTIVE` with `status:...
  body.adSetStatus (optional): "ACTIVE" | "PAUSED"
    Ad-set-level status, same semantics as `POST /v1/ads/create`. Sets the new ad set's switch alone and overrides `status` for it. A level status (`campaignStatus`, `adSetStatus`, `adStatus`) always wins for its level, and `status: PAUSED`...
  body.adStatus (optional): "ACTIVE" | "PAUSED"
    Ad-level status, same semantics as `POST /v1/ads/create`. Sets the new ads' switch and overrides `status` for them, also with `adSetId`. Send `campaignStatus`, `adSetStatus` and `adStatus` all PAUSED to create every object paused.
  body.bidStrategy (optional): "LOWEST_COST_WITHOUT_CAP" | "LOWEST_COST_WITH_BID_CAP" | "COST_CAP" | "LOWEST_COST_WITH_MIN_ROAS"
    Meta bid strategy applied to the shared ad set. Defaults to `LOWEST_COST_WITHOUT_CAP` (auto-bid) when omitted. `LOWEST_COST_WITH_BID_CAP` and `COST_CAP` require `bidAmount`. `LOWEST_COST_WITH_MIN_ROAS` requires `roasAverageFloor`....
  body.bidAmount (optional): number
    Whole currency units (e.g. `5` = $5.00 on a USD account). Required when `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`; rejected otherwise.
  body.roasAverageFloor (optional): number
    Decimal ROAS multiplier (e.g. `2.0` = 2.0× ROAS floor). Required when `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`; rejected otherwise. Meta enforces its own upper bound server-side.
  body.dsaBeneficiary (optional): string
    Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). Optional if the ad account has a default beneficiary: set it once via `PATCH /v1/ads/accounts` or in Meta Ads Manager, and Meta fills it in...
  body.dsaPayor (optional): string
    Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.
  body.regionalRegulatedCategories (optional): array<string>
    Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. AUSTRALIA_FINSERV, AUSTRALIA_UNIVERSAL, BRAZIL_REGULATION, INDIA_FINSERV, MALAYSIA_UNIVERSAL, SINGAPORE_UNIVERSAL, TAIWAN_FINSERV,...
  body.regionalRegulationIdentities (optional): object
    Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. Meta may require them on API-created ad sets even when a default...
query: no client-supplied fields

Request skeleton:
{
  "body": {
    "name": "Example Meta Ads resource"
  }
}

Local relationship syntax:
  {"$smallforce":{"kind":"campaign","id":"<local UUID>"}}
  {"$smallforceAsset":"<SmallForce asset UUID>"}

SmallForce injects provider account and primary-target IDs. Raw Meta IDs are
rejected, and every local reference is verified against the authenticated
organization, profile, connection, and ad account. Use --json for the full result.

smallforce ads google

Manage Google Ads through SmallForce-local, organization-scoped IDs

Full reference: Google Ads commands.

smallforce ads tiktok

Manage TikTok Ads through SmallForce-local, organization-scoped IDs

Full reference: TikTok Ads commands.