Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Snapchat Ads

Scalekit connector
Open markdown

The Snapchat Ads connector lets your AI agent act in each user's Snapchat Ads account. Each user signs in to Snapchat Ads once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 27 tools.

Tools
27
What they doRead · write · destructive
18 · 6 · 318 read6 write3 destructive
Users sign in with
OAuth app
Your own Snapchat Ads app

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 Snapchat Ads connection

    In AgentKit > Connections, create a Snapchat Ads connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Snapchat Ads connections use your own OAuth app. Register one with Snapchat Ads and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Snapchat Ads connection.

  5. 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 = 'snapchatads'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Snapchat Ads:', 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: 'snapchatads_me_get',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • snapchatads_account_ads_listList every ad in a Snapchat ad account.Read-only

    List Ads in Ad Account

    List every ad in a Snapchat ad account. Returns each ad's id, name, status, type, ad_squad_id, creative_id, review_status and delivery_status, plus paging.next_link. Use this for account-wide review, for example ads that were rejected. Use snapchatads_ads_list for one ad squad.

    Inputs

    ad_account_idstringrequired
    ID of the ad account. Get it from snapchatads_ad_accounts_list. Example: 8adc3db7-8148-4fbf-999c-8d2266369d74
    cursorstring
    Cursor for the next page, taken from the cursor parameter of paging.next_link in the previous response. Example: c2Q6MTIzNDU2
    limitinteger
    Number of results per page, 50 to 1000. Example: 100
  • snapchatads_ad_account_getGet one Snapchat ad account by ID.Read-only

    Get Ad Account

    Get one Snapchat ad account by ID. Returns its name, status, currency, timezone, lifetime spend cap and advertiser. Use this to check the currency and time zone before reading stats.

    Inputs

    ad_account_idstringrequired
    ID of the ad account. Get it from snapchatads_ad_accounts_list. Example: 8adc3db7-8148-4fbf-999c-8d2266369d74
  • snapchatads_ad_account_stats_getGet performance stats for a whole Snapchat ad account: impressions, swipes, spend, video views, conversions and other metrics.Read-only

    Get Ad Account Stats

    Get performance stats for a whole Snapchat ad account: impressions, swipes, spend, video views, conversions and other metrics. Returns timeseries (DAY or HOUR) or total stats with the requested fields; spend is in micro-currency. Use this to report on performance. Use the other stats tools for other levels.

    Inputs

    ad_account_idstringrequired
    ID of the ad account. Get it from snapchatads_ad_accounts_list. Example: 8adc3db7-8148-4fbf-999c-8d2266369d74
    granularitystringrequired
    Time grouping: TOTAL, DAY, HOUR or LIFETIME. DAY and HOUR need start_time and end_time. Example: DAYone of TOTALDAYHOURLIFETIME
    breakdownstring
    Split the results by child entity: campaign, ad. Example: campaignone of campaignad
    end_timestring
    End of the range (ISO 8601, on the hour). DAY ranges can span up to 31 days, HOUR ranges up to 7 days. Example: 2026-11-15T00:00:00-08:00
    fieldsstring
    Comma-separated metrics. Defaults to impressions,spend. Example: impressions,swipes,spend,video_views
    omit_emptyboolean
    Leave out rows with no data. Example: true
    start_timestring
    Start of the range (ISO 8601, on the hour; for DAY at midnight in the ad account's time zone). Example: 2026-11-01T00:00:00-08:00
    swipe_up_attribution_windowstring
    Swipe-up attribution window: 1_DAY, 7_DAY or 28_DAY (default). Example: 7_DAYone of 1_DAY7_DAY28_DAY
    view_attribution_windowstring
    View attribution window: none, 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default) or 7_DAY. Example: 1_DAYone of none1_HOUR3_HOUR6_HOUR1_DAY7_DAY
  • snapchatads_ad_accounts_listList the ad accounts of a Snapchat Business organization.Read-only

    List Ad Accounts

    List the ad accounts of a Snapchat Business organization. Returns each ad account's id, name, type, status, currency, timezone and funding sources. Use this to find an ad_account_id.

    Inputs

    organization_idstringrequired
    ID of the Snapchat Business organization. Get it from snapchatads_organizations_list. Example: 8adc3db7-8148-4fbf-999c-8d2266369d74
  • snapchatads_ad_getGet one Snapchat ad by ID.Read-only

    Get Ad

    Get one Snapchat ad by ID. Returns its name, status, type, creative_id, review_status, review_status_reasons and delivery_status. Use this to check why an ad is not delivering.

    Inputs

    ad_idstringrequired
    ID of the ad. Get it from snapchatads_ads_list. Example: 7e1d0e2b-9f3a-4c5e-8b1d-2f9b8c7a6d5e
  • snapchatads_ad_squad_getGet one Snapchat ad squad by ID.Read-only

    Get Ad Squad

    Get one Snapchat ad squad by ID. Returns its targeting, placement, bid strategy, optimization goal, budget, schedule and delivery_status. Use this when you know the ad squad ID.

    Inputs

    ad_squad_idstringrequired
    ID of the ad squad. Get it from snapchatads_ad_squads_list. Example: 23ac4ad3-1cde-4e32-9df5-5a3d6e8e6d75
  • snapchatads_ad_squad_stats_getGet performance stats for a Snapchat ad squad: impressions, swipes, spend, video views, conversions and other metrics.Read-only

    Get Ad Squad Stats

    Get performance stats for a Snapchat ad squad: impressions, swipes, spend, video views, conversions and other metrics. Returns timeseries (DAY or HOUR) or total stats with the requested fields; spend is in micro-currency. Use this to report on performance. Use the other stats tools for other levels.

    Inputs

    ad_squad_idstringrequired
    ID of the ad squad. Get it from snapchatads_ad_squads_list. Example: 23ac4ad3-1cde-4e32-9df5-5a3d6e8e6d75
    granularitystringrequired
    Time grouping: TOTAL, DAY, HOUR or LIFETIME. DAY and HOUR need start_time and end_time. Example: DAYone of TOTALDAYHOURLIFETIME
    breakdownstring
    Split the results by child entity: ad. Example: adone of ad
    end_timestring
    End of the range (ISO 8601, on the hour). DAY ranges can span up to 31 days, HOUR ranges up to 7 days. Example: 2026-11-15T00:00:00-08:00
    fieldsstring
    Comma-separated metrics. Defaults to impressions,spend. Example: impressions,swipes,spend,video_views
    omit_emptyboolean
    Leave out rows with no data. Example: true
    start_timestring
    Start of the range (ISO 8601, on the hour; for DAY at midnight in the ad account's time zone). Example: 2026-11-01T00:00:00-08:00
    swipe_up_attribution_windowstring
    Swipe-up attribution window: 1_DAY, 7_DAY or 28_DAY (default). Example: 7_DAYone of 1_DAY7_DAY28_DAY
    view_attribution_windowstring
    View attribution window: none, 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default) or 7_DAY. Example: 1_DAYone of none1_HOUR3_HOUR6_HOUR1_DAY7_DAY
  • snapchatads_ad_squads_listList the ad squads (targeting, budget and bid groups) of a Snapchat campaign.Read-only

    List Ad Squads

    List the ad squads (targeting, budget and bid groups) of a Snapchat campaign. Returns each ad squad's id, name, status, type, targeting, optimization_goal, bid and budget, plus paging.next_link. Use this to find an ad_squad_id.

    Inputs

    campaign_idstringrequired
    ID of the campaign. Get it from snapchatads_campaigns_list. Example: 6cf25572-048b-4447-95d1-eb47032fe4f3
    cursorstring
    Cursor for the next page, taken from the cursor parameter of paging.next_link in the previous response. Example: c2Q6MTIzNDU2
    limitinteger
    Number of results per page, 50 to 1000. Example: 100