Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to StackAdapt

Scalekit connector
Open markdown

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.

Tools
23
What they doRead · write · destructive
12 · 8 · 312 read8 write3 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .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.

  4. Authorize a user and make your first call

    quickstart.mts
    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)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their StackAdapt credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • stackadapt_get_adGet a single StackAdapt ad (creative) by ID.Read-only

    Get Ad

    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.

    Inputs

    ad_idstringrequired
    The StackAdapt ID of the ad, as a numeric string. Example: "12345". Find IDs with the matching list tool.
  • stackadapt_get_advertiserGet a single StackAdapt advertiser by ID.Read-only

    Get Advertiser

    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.

    Inputs

    advertiser_idstringrequired
    The StackAdapt ID of the advertiser, as a numeric string. Example: "12345". Find IDs with the matching list tool.
  • stackadapt_get_campaignGet a single StackAdapt campaign by ID, including its flights and attached ads.Read-only

    Get Campaign

    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.

    Inputs

    campaign_idstringrequired
    The StackAdapt ID of the campaign, as a numeric string. Example: "12345". Find IDs with the matching list tool.
  • stackadapt_get_campaign_deliveryGet 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.Read-only

    Get Campaign Delivery

    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.

    Inputs

    advertiser_idsarray
    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.
    afterstring
    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_idsarray
    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_idsarray
    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_typestring
    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 TABLEGRAPHdefault TABLE
    date_fromstring
    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_tostring
    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.
    firstinteger
    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
    granularitystring
    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 TOTALHOURLYDAILYWEEKLYMONTHLYdefault TOTAL
    statesarray
    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.
  • stackadapt_get_campaign_groupGet a single StackAdapt campaign group by ID, including its flights.Read-only

    Get Campaign Group

    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.

    Inputs

    campaign_group_idstringrequired
    The StackAdapt ID of the campaign group, as a numeric string. Example: "12345". Find IDs with the matching list tool.
  • stackadapt_get_campaign_group_deliveryGet 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.Read-only

    Get Campaign Group Delivery

    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.

    Inputs

    advertiser_idsarray
    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.
    afterstring
    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_idsarray
    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_typestring
    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 TABLEGRAPHdefault TABLE
    date_fromstring
    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_tostring
    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.
    firstinteger
    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
    granularitystring
    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 TOTALHOURLYDAILYWEEKLYMONTHLYdefault TOTAL
    statesarray
    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.
  • stackadapt_get_token_infoGet the identity and permissions of the StackAdapt API token in use, plus the StackAdapt account it belongs to.Read-only

    Get Token Info

    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.

    Inputs

    afterstring
    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.
    firstinteger
    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
  • stackadapt_list_adsList StackAdapt ads (creatives), optionally filtered by advertiser, campaign group, campaign, state, ad type, archived state, name or ID text, or specific IDs.Read-only

    List Ads

    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.

    Inputs

    advertiser_idsarray
    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.
    afterstring
    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.
    archivedboolean
    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_idsarray
    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_idsarray
    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.
    firstinteger
    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
    idsarray
    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_containsstring
    Case-insensitive text to search for within the name or ID of ads. Example: "spring". Leave empty to apply no text filter.
    statesarray
    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.
    typesarray
    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.