> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to StackAdapt

The StackAdapt connector lets your AI agent act in each user's StackAdapt account. Each user connects their own StackAdapt access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 23 tools.

**Authentication:** Bearer Token
**Categories:** Marketing
**Tools:** 23: 12 read, 8 write, 3 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=STACKADAPT)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the StackAdapt connection

   In **AgentKit > Connections**, create a StackAdapt connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'stackadapt'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize StackAdapt:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'stackadapt_get_campaign_delivery',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "stackadapt"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize StackAdapt:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="stackadapt_get_campaign_delivery",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their StackAdapt credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'stackadapt_get_ad',
  toolInput: {
    ad_id: '12345',
  },
  connector: 'stackadapt',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="stackadapt_get_ad",
    tool_input={
        "ad_id": "12345",
    },
    connection_name="stackadapt",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `stackadapt_get_ad`

Get Ad · Read-only

Get a single StackAdapt ad (creative) by ID.
Returns an ads.nodes list holding the ad's id, name, brand name, channel type (also in __typename), creative size, click URL, draft, archived, rejected and paused flags, creative state and status, impression tracker URLs, user metadata, campaign and rejection reasons; the list is empty when no ad has that ID.
Use this when you already have the ad ID; use stackadapt_list_ads to browse or search. StackAdapt has no single-ad query, so this filters the ads list by ID.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ad_id` (`string`, required): The StackAdapt ID of the ad, as a numeric string. Example: "12345". Find IDs with the matching list tool.

Example input: `{"ad_id":"12345"}`

### `stackadapt_get_advertiser`

Get Advertiser · Read-only

Get a single StackAdapt advertiser by ID.
Returns the advertiser's id, name, description, archived flag, deal IDs, excluded domains, inventory package strictness and user metadata; the advertiser field is null when no advertiser has that ID.
Use this when you already have the advertiser ID; use stackadapt_list_advertisers to search or browse.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `advertiser_id` (`string`, required): The StackAdapt ID of the advertiser, as a numeric string. Example: "12345". Find IDs with the matching list tool.

Example input: `{"advertiser_id":"12345"}`

### `stackadapt_get_campaign`

Get Campaign · Read-only

Get a single StackAdapt campaign by ID, including its flights and attached ads.
Returns the campaign's id, name, channel type (also in __typename), goal type, draft and archived flags, state and status, advertiser, campaign group, timezone, frequency caps, user metadata, up to 50 flights with bid, budget and dates, and up to 50 ads with their status; the campaign field is null when no campaign has that ID.
Use this when you already have the campaign ID; use stackadapt_list_campaigns to browse, stackadapt_get_ad for full ad details, and stackadapt_get_campaign_delivery for performance numbers.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `campaign_id` (`string`, required): The StackAdapt ID of the campaign, as a numeric string. Example: "12345". Find IDs with the matching list tool.

Example input: `{"campaign_id":"12345"}`

### `stackadapt_get_campaign_delivery`

Get Campaign Delivery · Read-only

Get delivery and performance stats (impressions, clicks, conversions, cost, CTR, CPM and more) for StackAdapt campaigns over a date range, bucketed by hour, day, week, month or in total.
Returns a union: when __typename is CampaignDeliveryOutcome it holds totalStats (aggregate across the filtered campaigns) and records, one per campaign and time bucket, with pageInfo for paging; when __typename is Progress the report is still being prepared and no stats are included, so call again with the same inputs after a few seconds.
Use this for campaign performance reporting; use stackadapt_get_campaign_group_delivery for stats rolled up by campaign group, and stackadapt_list_campaigns for campaign details. Narrow with advertiser_ids, campaign_group_ids, campaign_ids or states, since an unfiltered call covers every campaign.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `advertiser_ids` (`array`, optional): Restrict results to these advertiser IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `campaign_group_ids` (`array`, optional): Restrict results to these campaign group IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `campaign_ids` (`array`, optional): Restrict results to these campaign IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `data_type` (`string`, optional): Output format of the delivery data, TABLE or GRAPH. Defaults to TABLE; use GRAPH only when you specifically want the graph-oriented format. One of: `TABLE`, `GRAPH`. Default: `TABLE`.
- `date_from` (`string`, optional): Start of the reporting period as a YYYY-MM-DD date, inclusive. Example: "2026-09-01". Leave empty to use the StackAdapt default period.
- `date_to` (`string`, optional): End of the reporting period as a YYYY-MM-DD date, exclusive (the stats stop before this date). Example: "2026-10-01" covers through 2026-09-30. Leave empty to use the StackAdapt default.
- `first` (`integer`, optional): Maximum number of delivery records to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `granularity` (`string`, optional): How the stats are bucketed over time. Valid values are TOTAL (one aggregate), HOURLY, DAILY, WEEKLY and MONTHLY. Defaults to TOTAL. With DAILY, each record covers one day; combine with date_from and date_to to bound the range. One of: `TOTAL`, `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`. Default: `TOTAL`.
- `states` (`array`, optional): Restrict the campaigns to these states. Valid values are APPROVED, DRAFT, ENDED, ERROR, LIVE, PAUSED, PENDING and REJECTED. Provide a list, for example ["LIVE"]. Leave empty for no state filter.

Example input: `{}`

### `stackadapt_get_campaign_group`

Get Campaign Group · Read-only

Get a single StackAdapt campaign group by ID, including its flights.
Returns the group's id, name, advertiser, state and status, budget type and rollover, revenue type and pricing, timezone, frequency cap, domains and exclusions, user metadata, and up to 50 flights with dates and budgets; the campaignGroup field is null when no group has that ID.
Use this when you already have the campaign group ID; use stackadapt_list_campaign_groups to browse, and stackadapt_get_campaign_group_delivery for performance numbers.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `campaign_group_id` (`string`, required): The StackAdapt ID of the campaign group, as a numeric string. Example: "12345". Find IDs with the matching list tool.

Example input: `{"campaign_group_id":"12345"}`

### `stackadapt_get_campaign_group_delivery`

Get Campaign Group Delivery · Read-only

Get delivery and performance stats (impressions, clicks, conversions, cost, CTR, CPM and more) for StackAdapt campaign groups over a date range, bucketed by hour, day, week, month or in total.
Returns a union: when __typename is CampaignGroupDeliveryOutcome it holds totalStats (aggregate across the filtered groups) and records, one per campaign group and time bucket, with pageInfo for paging; when __typename is Progress the report is still being prepared and no stats are included, so call again with the same inputs after a few seconds.
Use this for stats rolled up by campaign group; use stackadapt_get_campaign_delivery for per-campaign stats, and stackadapt_list_campaign_groups for group details. Narrow with advertiser_ids, campaign_group_ids or states, since an unfiltered call covers every campaign group.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `advertiser_ids` (`array`, optional): Restrict results to these advertiser IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `campaign_group_ids` (`array`, optional): Restrict results to these campaign group IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `data_type` (`string`, optional): Output format of the delivery data, TABLE or GRAPH. Defaults to TABLE; use GRAPH only when you specifically want the graph-oriented format. One of: `TABLE`, `GRAPH`. Default: `TABLE`.
- `date_from` (`string`, optional): Start of the reporting period as a YYYY-MM-DD date, inclusive. Example: "2026-09-01". Leave empty to use the StackAdapt default period.
- `date_to` (`string`, optional): End of the reporting period as a YYYY-MM-DD date, exclusive (the stats stop before this date). Example: "2026-10-01" covers through 2026-09-30. Leave empty to use the StackAdapt default.
- `first` (`integer`, optional): Maximum number of delivery records to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `granularity` (`string`, optional): How the stats are bucketed over time. Valid values are TOTAL (one aggregate), HOURLY, DAILY, WEEKLY and MONTHLY. Defaults to TOTAL. With DAILY, each record covers one day; combine with date_from and date_to to bound the range. One of: `TOTAL`, `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`. Default: `TOTAL`.
- `states` (`array`, optional): Restrict the campaign groups to these states. Valid values are EMPTY, ENDED, INACTIVE, LIVE and PAUSED. Provide a list, for example ["LIVE"]. Leave empty for no state filter.

Example input: `{}`

### `stackadapt_get_token_info`

Get Token Info · Read-only

Get the identity and permissions of the StackAdapt API token in use, plus the StackAdapt account it belongs to.
Returns the token name, creation and expiry time, the account ID and currency, and for each advertiser the token can access, its READ or WRITE scopes.
Use this to confirm the connection works and to discover which advertiser IDs the token can see; use stackadapt_list_advertisers for advertiser details. Page through scopesByAdvertiser by passing pageInfo.endCursor as after.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `first` (`integer`, optional): Maximum number of advertiser scope entries to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.

Example input: `{}`

### `stackadapt_list_ads`

List Ads · Read-only

List StackAdapt ads (creatives), optionally filtered by advertiser, campaign group, campaign, state, ad type, archived state, name or ID text, or specific IDs.
Returns each ad's id, name, brand name, channel type (also in __typename), creative size, click URL, draft, archived, rejected and paused flags, creative state and status, and its campaign, plus totalCount and pageInfo for paging; it does not return delivery stats.
Use this to browse ads or find an ad ID; use stackadapt_get_ad for one ad with tracker URLs and rejection reasons. Pass pageInfo.endCursor as after to get the next page.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `advertiser_ids` (`array`, optional): Restrict results to these advertiser IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `archived` (`boolean`, optional): Filter ads by archived state: true returns only archived ads, false returns only non-archived ads. Leave empty to send no archived filter and use the StackAdapt default.
- `campaign_group_ids` (`array`, optional): Restrict results to these campaign group IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `campaign_ids` (`array`, optional): Restrict results to these campaign IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `first` (`integer`, optional): Maximum number of ads to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `ids` (`array`, optional): Restrict results to these ad IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `name_or_id_contains` (`string`, optional): Case-insensitive text to search for within the name or ID of ads. Example: "spring". Leave empty to apply no text filter.
- `states` (`array`, optional): Restrict results to ads in these creative states. Valid values are APPROVED, DRAFT, ENDED, ERROR, LIVE, PAUSED, PENDING and REJECTED. Provide a list, for example ["LIVE", "PENDING"]. Leave empty for no state filter.
- `types` (`array`, optional): Restrict results to these ad types. Valid values are Audio, CTV, DOOH, Display, Native, ProgrammaticLinearTv and Video (case-sensitive). Provide a list, for example ["Display", "Video"]. Leave empty for all ad types.

Example input: `{}`

### `stackadapt_list_advertisers`

List Advertisers · Read-only

List the advertisers in the StackAdapt account, optionally filtered by archived state, name or ID text, or specific IDs.
Returns each advertiser's id, name, description, archived flag, deal IDs, excluded domains and user metadata, plus totalCount and pageInfo for paging.
Use this to browse advertisers or find an advertiser ID; use stackadapt_get_advertiser for one advertiser by ID. Pass pageInfo.endCursor as after to get the next page.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `archived` (`boolean`, optional): Filter advertisers by archived state: true returns only archived advertisers, false returns only non-archived advertisers. Leave empty to send no archived filter and use the StackAdapt default.
- `first` (`integer`, optional): Maximum number of advertisers to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `ids` (`array`, optional): Restrict results to these advertiser IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `name_or_id_contains` (`string`, optional): Case-insensitive text to search for within the name or ID of advertisers. Example: "spring". Leave empty to apply no text filter.

Example input: `{}`

### `stackadapt_list_campaign_groups`

List Campaign Groups · Read-only

List StackAdapt campaign groups, optionally filtered by advertiser, state, archived state, name or ID text, or specific IDs.
Returns each campaign group's id, name, advertiser, state and status, budget type, budget rollover, revenue type and pricing, timezone and creation time, plus totalCount and pageInfo for paging; it does not return flights or delivery stats.
Use this to browse campaign groups or find a campaign group ID; use stackadapt_get_campaign_group for one group with its flights. Pass pageInfo.endCursor as after to get the next page.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `advertiser_ids` (`array`, optional): Restrict results to these advertiser IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `archived` (`boolean`, optional): Filter campaign groups by archived state: true returns only archived campaign groups, false returns only non-archived campaign groups. Leave empty to send no archived filter and use the StackAdapt default.
- `first` (`integer`, optional): Maximum number of campaign groups to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `ids` (`array`, optional): Restrict results to these campaign group IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `name_or_id_contains` (`string`, optional): Case-insensitive text to search for within the name or ID of campaign groups. Example: "spring". Leave empty to apply no text filter.
- `states` (`array`, optional): Restrict results to campaign groups in these states. Valid values are EMPTY (no campaigns), ENDED (budget or end date reached), INACTIVE (no live campaigns), LIVE and PAUSED. Provide a list, for example ["LIVE", "PAUSED"]. Leave empty for no state filter.

Example input: `{}`

### `stackadapt_list_campaigns`

List Campaigns · Read-only

List StackAdapt campaigns, optionally filtered by advertiser, campaign group, state, channel type, archived state, name or ID text, or specific IDs, and sorted by name, status, budget, creation date or stats.
Returns each campaign's id, name, channel type (also in __typename), goal type, draft and archived flags, state and status, advertiser, campaign group, timezone, and created and updated times, plus totalCount and pageInfo for paging; it does not return flights, ads or delivery stats.
Use this to browse campaigns or find a campaign ID; use stackadapt_get_campaign for one campaign with flights and ads, and stackadapt_get_campaign_delivery for performance numbers. Pass pageInfo.endCursor as after to get the next page.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `advertiser_ids` (`array`, optional): Restrict results to these advertiser IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `archived` (`boolean`, optional): Filter campaigns by archived state: true returns only archived campaigns, false returns only non-archived campaigns. Leave empty to send no archived filter and use the StackAdapt default.
- `campaign_group_ids` (`array`, optional): Restrict results to these campaign group IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `first` (`integer`, optional): Maximum number of campaigns to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `ids` (`array`, optional): Restrict results to these campaign IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `name_or_id_contains` (`string`, optional): Case-insensitive text to search for within the name or ID of campaigns. Example: "spring". Leave empty to apply no text filter.
- `sort_field` (`string`, optional): Field to sort campaigns by. Valid values are BUDGET, CREATED_AT, NAME, STATS and STATUS. Leave empty to use the StackAdapt default order. Use sort_order to set the direction. One of: `BUDGET`, `CREATED_AT`, `NAME`, `STATS`, `STATUS`.
- `sort_order` (`string`, optional): Sort direction, ASC or DESC. Only used when sort_field is set; defaults to ASC. Example: sort_field CREATED_AT with sort_order DESC lists the newest campaigns first. One of: `ASC`, `DESC`. Default: `ASC`.
- `states` (`array`, optional): Restrict results to campaigns in these states. Valid values are APPROVED (not started yet), DRAFT, ENDED, ERROR, LIVE, PAUSED, PENDING (live but creatives pending) and REJECTED. Provide a list, for example ["LIVE", "PAUSED"]. Leave empty for no state filter.
- `types` (`array`, optional): Restrict results to these campaign channel types. Valid values are AUDIO, CTV, DISPLAY, DOOH, NATIVE, PROGRAMMATIC_LINEAR_TV and VIDEO. Provide a list, for example ["DISPLAY", "NATIVE"]. Leave empty for all channel types.

Example input: `{}`

### `stackadapt_list_custom_segments`

List Custom Segments · Read-only

List StackAdapt custom audience segments, optionally filtered by name, type, provider or specific IDs, and sorted by name or creation date.
Returns each segment's id, name, description, segment type (in __typename), active and expandable flags, size, DUID size, phrases and creation time, plus totalCount and pageInfo for paging.
Use this to browse audiences or find a segment ID before targeting; set include_public to true to also see public third-party catalogue segments. Pass pageInfo.endCursor as after to get the next page.
GraphQL errors are returned with HTTP 200 in an errors array, so check it on every response.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): Pagination cursor for the next page. Leave empty for the first page. When the previous response shows pageInfo.hasNextPage as true, pass its pageInfo.endCursor value here unchanged to get the following page.
- `first` (`integer`, optional): Maximum number of custom segments to return in this page, as a positive integer. Defaults to 50. If the response pageInfo.hasNextPage is true, request the next page by passing pageInfo.endCursor as the after input. Default: `50`.
- `ids` (`array`, optional): Restrict results to these custom segment IDs. Provide a list of numeric ID strings, for example ["12345"]. Leave empty to apply no filter on this field.
- `include_public` (`boolean`, optional): Set true to also return publicly accessible segments such as third-party catalogue segments. Defaults to false on the StackAdapt side when omitted. Public segments may not be usable in a campaign unless the account has requested them.
- `name_contains` (`string`, optional): Text that the segment name must contain. Example: "newsletter". Leave empty to apply no name filter.
- `providers` (`array`, optional): Restrict results to segments created with these data providers, as a list of provider name strings. Example: ["StackAdapt"]. Leave empty for all providers.
- `sort_field` (`string`, optional): Field to sort segments by: created_at (newest first when sort_order is DESC) or name. Leave empty to use the StackAdapt default order. Use sort_order to set the direction. One of: `created_at`, `name`.
- `sort_order` (`string`, optional): Sort direction, ASC or DESC. Only used when sort_field is set; defaults to ASC. One of: `ASC`, `DESC`. Default: `ASC`.
- `types` (`array`, optional): Restrict results to these custom segment types, for example ["LOCATION_BASED", "KEYWORDS"]. Valid values are AUDIENCE_EXTENSION, B2B, CATEGORIES, COMBINED_AUDIENCE, DEVICE, INTERSECTION, IP, ISP, KEYPHRASE_RULES, KEYWORDS, KEYWORDS_AND_SITES, KEYWORDS_OR_SITES, LOCATION_BASED, LOOKALIKE_AUDIENCE, NPI_AUDIENCE, PLACEHOLDER, SITES, THIRD_PARTY, THIRD_PARTY_CRM, TOPICS, USER_UPLOADED. Leave empty for all types.

Example input: `{}`

### `stackadapt_create_campaign_group`

Create Campaign Group · Write

Create a campaign group under a StackAdapt advertiser to set shared budget, flight dates and delivery rules for the campaigns inside it.
Returns the new campaign group's id, name, budget type, status, advertiser and flights, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to start a new group; use stackadapt_update_campaign_group to change an existing one and stackadapt_pause_campaign_group to stop delivery.
Requires an existing advertiser ID (find it with stackadapt_list_advertisers) and at least one flight.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `advertiserId` (`string`, required): ID of the advertiser that owns the campaign group. All campaigns in the group use this advertiser. Required when creating a group. Example: "123456".
- `flights` (`array`, required): List of flights (budget periods) for the campaign group, required to create a group. Each flight has a start and end time in ISO 8601 and a lifetime budget, a daily budget or both, in the unit of budgetType. Flights can also set even pacing, a pace-ahead percentage, a margin and weekday parting. Example: [{"startTime":"2026-11-01T00:00:00Z","endTime":"2026-11-30T23:59:59Z","lifetimeBudget":5000,"dailyBudget":200,"isPaceEvenly":true}].
- `name` (`string`, required): Name of the campaign group, shown in StackAdapt. Required when creating a group. Example: "Holiday 2026 Prospecting".
- `budgetAllocation` (`object`, optional): How the group's budget is divided among its campaigns. allocationType is required and is CBBA (click-based), PBBA (performance-based), RBBA (rank-based) or SBBA (scale-based). Optional settings give a minimum shared percent (10 to 50), a ranking with per-campaign caps for rank-based allocation, and a cap for unranked campaigns. Example: {"allocationType":"PBBA","minBudgetAllocationPercent":20}.
- `budgetRollover` (`boolean`, optional): True to roll unspent budget over to the next flight. Example: true.
- `budgetType` (`string`, optional): How the group's budget is measured and allocated: click, cost, imp (impressions) or revenue. The budgets in flights are expressed in this unit. Example: "cost". One of: `click`, `cost`, `imp`, `revenue`.
- `domainExclusions` (`array`, optional): Internet domains excluded from the inventory of every campaign in the group. Example: ["blocked.example.com"].
- `domains` (`array`, optional): Internet domains where ads of the group's campaigns may be shown. Example: ["example.com","news.example.org"].
- `freqCapExpiry` (`integer`, optional): Time in minutes before the frequency cap resets. Use together with freqCapLimit. Example: 1440 for one day.
- `freqCapLimit` (`integer`, optional): Maximum number of times a unique user can view an ad. Use together with freqCapExpiry. Example: 5.
- `inventoryPackageIds` (`array`, optional): IDs of the inventory packages (curated bundles of exchange and publisher inventory) tied to the group. Example: ["101","102"].
- `isInventoryPackagesStrict` (`boolean`, optional): True to restrict the group's campaigns to run only on the listed inventory packages. Example: false.
- `revenuePricing` (`number`, optional): Expected revenue the group aims to generate, used with a revenue budgetType. When revenueType is MARGIN this is the margin percentage (10 means 10 percent). Example: 2.5.
- `revenueType` (`string`, optional): Revenue model of the campaign group: CPC, CPM or MARGIN. Used together with revenuePricing and a revenue budgetType. Example: "CPM". One of: `CPC`, `CPM`, `MARGIN`.
- `userMetadata` (`array`, optional): Custom key/value metadata stored on the campaign group (StackAdapt marks this field as alpha). Each entry has a string key and a string value. Example: [{"key":"team","value":"growth"}].

Example input: `{"advertiserId":"123456","flights":[{"startTime":"2026-11-01T00:00:00Z","endTime":"2026-11-30T23:59:59Z","lifetimeBudget":5000,"dailyBudget":200,"isPaceEvenly":true}],"name":"Holiday 2026 Prospecting"}`

### `stackadapt_pause_ad`

Pause Ads · Write

Pause one or more StackAdapt ads (creatives) so they stop serving.
Returns pausedCount (ads that were not already paused), each ad's id, name, paused flag and creative status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to stop individual ads; stackadapt_resume_ad restarts them and stackadapt_archive_ad retires them. To stop whole campaigns use stackadapt_pause_campaign.
Requires the ad IDs (find them with stackadapt_list_ads).

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `adIds` (`array`, required): IDs of the ads to act on, as strings. Pass one ID to act on a single ad. Example: ["5001","5002"].

Example input: `{"adIds":["5001","5002"]}`

### `stackadapt_pause_campaign`

Pause Campaigns · Write

Pause one or more StackAdapt campaigns so they stop delivering, recording a reason.
Returns pausedCount (campaigns that were not already paused), each campaign's id, name and status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to stop delivery temporarily; stackadapt_resume_campaign restarts it and stackadapt_archive_campaign retires a campaign for good. To stop every campaign in a group use stackadapt_pause_campaign_group.
Requires the campaign IDs (find them with stackadapt_list_campaigns) and a pause reason.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `campaignIds` (`array`, required): IDs of the campaigns to act on, as strings. Pass one ID to act on a single campaign. Example: ["1001","1002"].
- `reason` (`string`, required): Why the campaign is being paused. One of BRAND_LIFT, COVID_19, GOAL_REACHED, OTHER, PERFORMANCE or RECREATING. Required by StackAdapt. Example: "PERFORMANCE". One of: `BRAND_LIFT`, `COVID_19`, `GOAL_REACHED`, `OTHER`, `PERFORMANCE`, `RECREATING`.
- `reasonText` (`string`, optional): Free-text explanation for pausing the campaign. Optional, and most useful with reason OTHER. Example: "Pausing while creatives are refreshed."

Example input: `{"campaignIds":["1001","1002"],"reason":"PERFORMANCE"}`

### `stackadapt_pause_campaign_group`

Pause Campaign Group · Write

Pause a StackAdapt campaign group so the campaigns inside it stop delivering, recording a reason.
Returns the paused campaign group's id, name and status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to stop a whole group at once; stackadapt_resume_campaign_group restarts it and stackadapt_archive_campaign_group retires it. To stop individual campaigns use stackadapt_pause_campaign.
Requires the campaign group ID (find it with stackadapt_list_campaign_groups) and a pause reason.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the campaign group to pause. Example: "456789".
- `reason` (`string`, required): Why the campaign group is being paused. One of BRAND_LIFT, COVID_19, GOAL_REACHED, OTHER, PERFORMANCE or RECREATING. Required by StackAdapt. Example: "PERFORMANCE". One of: `BRAND_LIFT`, `COVID_19`, `GOAL_REACHED`, `OTHER`, `PERFORMANCE`, `RECREATING`.
- `reasonText` (`string`, optional): Free-text explanation for pausing the campaign group. Optional, and most useful with reason OTHER. Example: "Pausing while creatives are refreshed."

Example input: `{"id":"456789","reason":"PERFORMANCE"}`

### `stackadapt_resume_ad`

Resume Ads · Write

Resume one or more paused StackAdapt ads (creatives) so they serve again.
Returns resumedCount (ads that were not already running), each ad's id, name, paused flag and creative status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this after stackadapt_pause_ad. An ad still will not serve if its campaign or group is paused, so check the returned creative status.
Requires the ad IDs (find them with stackadapt_list_ads).

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `adIds` (`array`, required): IDs of the ads to act on, as strings. Pass one ID to act on a single ad. Example: ["5001","5002"].

Example input: `{"adIds":["5001","5002"]}`

### `stackadapt_resume_campaign`

Resume Campaigns · Write

Resume one or more paused StackAdapt campaigns so they deliver again.
Returns resumedCount (campaigns that were not already active), each campaign's id, name and status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this after stackadapt_pause_campaign; to restart a whole group use stackadapt_resume_campaign_group. A resumed campaign may still not deliver if its group is paused or it has ended, so check the returned status.
Requires the campaign IDs (find them with stackadapt_list_campaigns).

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `campaignIds` (`array`, required): IDs of the campaigns to act on, as strings. Pass one ID to act on a single campaign. Example: ["1001","1002"].

Example input: `{"campaignIds":["1001","1002"]}`

### `stackadapt_resume_campaign_group`

Resume Campaign Group · Write

Resume a paused StackAdapt campaign group so its live campaigns deliver again.
Returns the resumed campaign group's id, name and status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this after stackadapt_pause_campaign_group; to restart individual campaigns use stackadapt_resume_campaign.
Requires the campaign group ID (find it with stackadapt_list_campaign_groups).

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the campaign group to resume. Example: "456789".

Example input: `{"id":"456789"}`

### `stackadapt_update_campaign_group`

Update Campaign Group · Write

Update a StackAdapt campaign group's name, advertiser, budget settings, flights, domains, frequency cap or inventory packages.
Returns the updated campaign group's id, name, budget type, status, advertiser and flights, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to edit an existing group; use stackadapt_create_campaign_group for a new one, and stackadapt_pause_campaign_group or stackadapt_archive_campaign_group to stop it. Fields you leave out are not sent.
Requires the campaign group ID (find it with stackadapt_list_campaign_groups).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ID of the campaign group to update. Example: "456789".
- `advertiserId` (`string`, optional): ID of the advertiser to link the campaign group to. Leave it out to keep the current advertiser. Example: "123456".
- `budgetAllocation` (`object`, optional): How the group's budget is divided among its campaigns. allocationType is required and is CBBA (click-based), PBBA (performance-based), RBBA (rank-based) or SBBA (scale-based). Optional settings give a minimum shared percent (10 to 50), a ranking with per-campaign caps for rank-based allocation, and a cap for unranked campaigns. Example: {"allocationType":"PBBA","minBudgetAllocationPercent":20}.
- `budgetRollover` (`boolean`, optional): True to roll unspent budget over to the next flight. Example: true.
- `budgetType` (`string`, optional): How the group's budget is measured and allocated: click, cost, imp (impressions) or revenue. The budgets in flights are expressed in this unit. Example: "cost". One of: `click`, `cost`, `imp`, `revenue`.
- `domainExclusions` (`array`, optional): Internet domains excluded from the inventory of every campaign in the group. Example: ["blocked.example.com"].
- `domains` (`array`, optional): Internet domains where ads of the group's campaigns may be shown. Example: ["example.com","news.example.org"].
- `flights` (`array`, optional): Flights (budget periods) for the campaign group. Include a flight's id to target an existing flight; objects without an id describe new flights. Each flight has a start and end time in ISO 8601 and a lifetime budget, a daily budget or both, in the unit of budgetType. StackAdapt does not document whether sending flights merges with or replaces the group's existing flights, so include every flight you want to keep and check the returned flights to confirm the result. Example: [{"id":"789","endTime":"2026-12-15T23:59:59Z","dailyBudget":250}].
- `freqCapExpiry` (`integer`, optional): Time in minutes before the frequency cap resets. Use together with freqCapLimit. Example: 1440 for one day.
- `freqCapLimit` (`integer`, optional): Maximum number of times a unique user can view an ad. Use together with freqCapExpiry. Example: 5.
- `inventoryPackageIds` (`array`, optional): IDs of the inventory packages (curated bundles of exchange and publisher inventory) tied to the group. Example: ["101","102"].
- `isInventoryPackagesStrict` (`boolean`, optional): True to restrict the group's campaigns to run only on the listed inventory packages. Example: false.
- `name` (`string`, optional): New name for the campaign group. Leave it out to keep the current name. Example: "Holiday 2026 Prospecting".
- `revenuePricing` (`number`, optional): Expected revenue the group aims to generate, used with a revenue budgetType. When revenueType is MARGIN this is the margin percentage (10 means 10 percent). Example: 2.5.
- `revenueType` (`string`, optional): Revenue model of the campaign group: CPC, CPM or MARGIN. Used together with revenuePricing and a revenue budgetType. Example: "CPM". One of: `CPC`, `CPM`, `MARGIN`.
- `userMetadata` (`array`, optional): Custom key/value metadata stored on the campaign group (StackAdapt marks this field as alpha). Each entry has a string key and a string value. Example: [{"key":"team","value":"growth"}].

Example input: `{"id":"456789"}`

### `stackadapt_archive_ad`

Archive Ads · Destructive

Archive one or more StackAdapt ads (creatives) so they are retired and no longer active.
Returns archivedCount (ads that were not already archived), each ad's id, name, archived flag and creative status, plus userErrors. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to retire ads for good. Use stackadapt_pause_ad instead if you may want to resume them later.
Requires the ad IDs (find them with stackadapt_list_ads).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`array`, required): IDs of the ads to act on, as strings. Pass one ID to act on a single ad. Example: ["5001","5002"].

Example input: `{"ids":["5001","5002"]}`

### `stackadapt_archive_campaign`

Archive Campaign · Destructive

Archive a StackAdapt campaign so it is retired and no longer active.
Returns only userErrors; an empty list means the campaign was archived. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to retire a campaign for good. Use stackadapt_pause_campaign instead if you may want to resume it later.
Requires the campaign ID (find it with stackadapt_list_campaigns).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the campaign to archive. Example: "1001".

Example input: `{"id":"1001"}`

### `stackadapt_archive_campaign_group`

Archive Campaign Group · Destructive

Archive a StackAdapt campaign group so it is retired and no longer active.
Returns only userErrors; an empty list means the campaign group was archived. Failures are reported in userErrors with HTTP 200 (check it first); request-level problems such as an invalid token come back in a top-level errors array.
Use this to retire a group for good. Use stackadapt_pause_campaign_group instead if you may want to resume it later.
Requires the campaign group ID (find it with stackadapt_list_campaign_groups).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ID of the campaign group to archive. Example: "456789".

Example input: `{"id":"456789"}`

## Related

Other Marketing connectors ([all 190](/agentkit/connectors/?category=marketing)):

- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools
- [Twitter / X](/agentkit/connectors/twitteroauth/): Scalekit connector, OAuth, 92 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
