The X Ads MCP connector routes your AI agent's tool calls to X Ads's own MCP server through Scalekit. Each user signs in to X Ads once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 74 tools.
- Tools
- 74
- What they doRead · write · destructive
- 40 · 23 · 1140 read23 write11 destructive
- Users sign in with
- OAuth
- OAuth app
- Your own X Ads MCP server app
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. 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>Create the X Ads connection
In AgentKit > Connections, create a X Ads connection and copy its redirect URI. The name you give it is the
connection_nameyour code passes. See Configure connections.Register an OAuth app
X Ads MCP server connections use your own OAuth app. Register one with X Ads MCP server and add the redirect URI you copied.
Then enter the app's Client ID and Client Secret on the X Ads connection.
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.actionsconst connector = 'xadsmcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize X Ads:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'xadsmcp_list_ads_accounts',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_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.actionsconnection_name = "xadsmcp"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize X Ads:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="xadsmcp_list_ads_accounts",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolxadsmcp_estimate_audienceEstimate the audience size for a set of targeting criteria (JSON body of targeting criterion objects)Read-onlyEstimate Audience
Estimate the audience size for a set of targeting criteria (JSON body of targeting criterion objects)
Inputs
account_idstringrequired- The ID of the ads account.
targeting_criteriaarrayrequired- Targeting criterion objects to size. Each also carries a targeting_value whose JSON type varies b...
xadsmcp_get_account_mediaGet a single account media object by IDRead-onlyGet Account Media
Get a single account media object by ID
Inputs
account_idstringrequired- The ID of the ads account.
account_media_idstringrequired- The ID of the account media item.
with_deletedboolean- Include the record even if soft-deleted (default false).
xadsmcp_get_account_statsGet synchronous analytics (impressions, engagements, spend) for an ads accountRead-onlyGet Account Stats
Get synchronous analytics (impressions, engagements, spend) for an ads account
Inputs
account_idstringrequired- The ID of the ads account.
end_timestringrequired- ISO 8601 end of the metrics window (exclusive).
entitystringrequired- Entity type to fetch metrics for.one of
ACCOUNTCAMPAIGNFUNDING_INSTRUMENTLINE_ITEMMEDIA_CREATIVEPROMOTED_ACCOUNTPROMOTED_TWEETORGANIC_TWEET entity_idsstringrequired- Comma-separated IDs of the entities to fetch metrics for (max 20).
granularitystringrequired- Granularity of the returned time series.one of
DAYHOURTOTAL metric_groupsstringrequired- Comma-separated metric groups, e.g. ENGAGEMENT,BILLING,VIDEO (max 10; MOBILE_CONVERSION groups mu...
placementstringrequired- Placement to scope the metrics to.one of
ALL_ON_TWITTERPUBLISHER_NETWORK start_timestringrequired- ISO 8601 start of the metrics window, e.g. 2026-07-01T00:00:00Z.
xadsmcp_get_active_entitiesList which ads entities had metrics change in a time window (use before requesting account stats)Read-onlyGet Active Entities
List which ads entities had metrics change in a time window (use before requesting account stats)
Inputs
account_idstringrequired- The ID of the ads account.
end_timestringrequired- ISO 8601 end of the activity window (exclusive); must be a whole hour (minutes and seconds 0).
entitystringrequired- Entity type to check for metric activity.one of
CAMPAIGNFUNDING_INSTRUMENTLINE_ITEMMEDIA_CREATIVEPROMOTED_ACCOUNTPROMOTED_TWEET start_timestringrequired- ISO 8601 start of the activity window; must be a whole hour (minutes and seconds 0).
campaign_idsstring- Comma-separated campaign IDs to scope the check to (max 200; exclusive with the other ids filters).
funding_instrument_idsstring- Comma-separated funding instrument IDs to scope the check to (max 200; exclusive with the other i...
line_item_idsstring- Comma-separated line item IDs to scope the check to (max 200; exclusive with the other ids filters).
xadsmcp_get_app_event_tagGet a single mobile app conversion event tag by IDRead-onlyGet App Event Tag
Get a single mobile app conversion event tag by ID
Inputs
account_idstringrequired- The ID of the ads account.
app_event_tag_idstringrequired- The ID of the app event tag.
with_deletedboolean- Include the tag even if soft-deleted (default false).
xadsmcp_get_app_listGet a single app list by IDRead-onlyGet App List
Get a single app list by ID
Inputs
account_idstringrequired- The ID of the ads account.
app_list_idstringrequired- The ID of the app list.
with_deletedboolean- Include the app list even if soft-deleted (default false).
xadsmcp_get_campaignGet a single campaign by IDRead-onlyGet Campaign
Get a single campaign by ID
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idstringrequired- The ID of the campaign to retrieve.
with_deletedboolean- Include the campaign even if soft-deleted (default false).
xadsmcp_get_campaign_reachGet reach and average-frequency metrics for campaignsRead-onlyGet Campaign Reach
Get reach and average-frequency metrics for campaigns
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idsstringrequired- Comma-separated campaign IDs to fetch reach for (max 20).
end_timestringrequired- ISO 8601 end of the metrics window (exclusive); must be in the past (a future end_time is rejected).
start_timestringrequired- ISO 8601 start of the metrics window.
xadsmcp_get_cardGet a single card by IDRead-onlyGet Card
Get a single card by ID
Inputs
account_idstringrequired- The ID of the ads account.
card_idstringrequired- The ID of the card.
with_deletedboolean- Include the card even if soft-deleted (default false).
xadsmcp_get_custom_audienceGet a single custom audience by IDRead-onlyGet Custom Audience
Get a single custom audience by ID
Inputs
account_idstringrequired- The ID of the ads account.
custom_audience_idstringrequired- The ID of the custom audience.
with_deletedboolean- Include the audience even if soft-deleted (default false).
xadsmcp_get_funding_instrumentGet a single funding instrument by IDRead-onlyGet Funding Instrument
Get a single funding instrument by ID
Inputs
account_idstringrequired- The ID of the ads account.
funding_instrument_idstringrequired- The ID of the funding instrument.
with_deletedboolean- Include the funding instrument even if soft-deleted (default false).
xadsmcp_get_line_itemGet a single line item by IDRead-onlyGet Line Item
Get a single line item by ID
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idstringrequired- The ID of the line item to retrieve.
with_deletedboolean- Include the line item even if soft-deleted (default false).
xadsmcp_get_media_creativeGet a single media creative by IDRead-onlyGet Media Creative
Get a single media creative by ID
Inputs
account_idstringrequired- The ID of the ads account.
media_creative_idstringrequired- The ID of the media creative.
with_deletedboolean- Include the media creative even if soft-deleted (default false).
xadsmcp_get_media_library_itemGet a single media library object by media keyRead-onlyGet Media Library Item
Get a single media library object by media key
Inputs
account_idstringrequired- The ID of the ads account.
media_keystringrequired- The media key of the media library item.
xadsmcp_get_promoted_postGet a single promoted post by IDRead-onlyGet Promoted Post
Get a single promoted post by ID
Inputs
account_idstringrequired- The ID of the ads account.
promoted_tweet_idstringrequired- The ID of the promoted post (promoted tweet).
with_deletedboolean- Include the promoted post even if soft-deleted (default false).
xadsmcp_get_targeting_criterionGet a single targeting criterion by IDRead-onlyGet Targeting Criterion
Get a single targeting criterion by ID
Inputs
account_idstringrequired- The ID of the ads account.
targeting_criterion_idstringrequired- The ID of the targeting criterion.
langstring- BCP-47 language code; adds a localized_name response attribute for localizable criteria.
with_deletedboolean- Include the criterion even if soft-deleted (default false).
xadsmcp_get_tracking_tagGet a single tracking tag by IDRead-onlyGet Tracking Tag
Get a single tracking tag by ID
Inputs
account_idstringrequired- The ID of the ads account.
tracking_tag_idstringrequired- The ID of the tracking tag.
with_deletedboolean- Include the tracking tag even if soft-deleted (default false).
xadsmcp_get_web_event_tagGet a single website conversion event tag by IDRead-onlyGet Web Event Tag
Get a single website conversion event tag by ID
Inputs
account_idstringrequired- The ID of the ads account.
web_event_tag_idstringrequired- The ID of the web event tag.
with_deletedboolean- Include the tag even if soft-deleted (default false).
xadsmcp_list_account_mediaList the account media (promotion-eligible creatives) in an ads accountRead-onlyList Account Media
List the account media (promotion-eligible creatives) in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
account_media_idsstring- Comma-separated account media IDs to fetch specific records (max 200).
countinteger- Number of records to return per page (default 200, max 1000).
creative_typesstring- Comma-separated creative types to filter by, e.g. BANNER, INTERSTITIAL, PREROLL, VAST_PREROLL.
cursorstring- Pagination cursor from a previous response.
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted records (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_account_postsList posts (tweets) usable for promotion by an ads accountRead-onlyList Account Posts
List posts (tweets) usable for promotion by an ads account
Inputs
account_idstringrequired- The ID of the ads account.
tweet_typestringrequired- Post type to list (the legacy API requires this filter).one of
PUBLISHEDSCHEDULEDDRAFT countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
include_mentions_and_repliesboolean- Include mentions and replies in the results (default false).
timeline_typestring- Scope to promoted-only, organic or all posts (default NULLCAST).one of
ALLNULLCASTORGANIC trim_userboolean- Return only the author's user ID instead of the full user object (default false).
tweet_idsstring- Comma-separated post (tweet) IDs to scope the response to.
user_idstring- Promotable user whose posts to list (defaults to the account's own user).
xadsmcp_list_ads_accountsList the ads accounts the authenticated user can accessRead-onlyList Ads Accounts
List the ads accounts the authenticated user can access
Inputs
account_idsstring- Comma-separated account IDs to fetch specific records (max 200).
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
qstring- Search by account name (1-255 characters).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted accounts (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_app_listsList the app lists in an ads accountRead-onlyList App Lists
List the app lists in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
app_list_idsstring- Comma-separated app list IDs to fetch specific records (max 200).
countinteger- Number of records to return per page (default 200, max 1000).
cursorstring- Pagination cursor from a previous response.
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted records (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_campaignsList campaigns for an accountRead-onlyList Campaigns
List campaigns for an account
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idsstring- Comma-separated campaign IDs to scope the response to.
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
funding_instrument_idsstring- Comma-separated funding instrument IDs to scope the results to (max 200).
qstring- Search by campaign name (1-255 characters).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted campaigns in the response (default false).
with_draftboolean- Include draft campaigns in the response (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_cardsList the cards in an ads accountRead-onlyList Cards
List the cards in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
card_idsstring- Comma-separated card IDs to fetch specific cards (max 200).
card_typesstring- Comma-separated unified card types to filter by, e.g. IMAGE_WEBSITE, VIDEO_WEBSITE, IMAGE_APP, VI...
card_urisstring- Comma-separated card URIs to fetch specific cards (max 200).
countinteger- Number of records to return per page (default 100, max 200).
cursorstring- Pagination cursor from a previous response.
include_legacy_cardsboolean- Include legacy (non-unified) cards in the response (default false).
qstring- Search query matching against the card name.
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted cards (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_custom_audience_targetedList the line items and campaigns targeting a custom audienceRead-onlyList Custom Audience Targeted
List the line items and campaigns targeting a custom audience
Inputs
account_idstringrequired- The ID of the ads account.
custom_audience_idstringrequired- The ID of the custom audience.
countinteger- Number of records to return per page (default 200, max 1000).
cursorstring- Pagination cursor from a previous response.
with_activeboolean- Restrict to line items with ACTIVE serving status (default true per the legacy API).
xadsmcp_list_custom_audiencesList the custom audiences in an ads accountRead-onlyList Custom Audiences
List the custom audiences in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
countinteger- Number of records to return per page (default 200, max 1000).
cursorstring- Pagination cursor from a previous response.
custom_audience_idsstring- Comma-separated custom audience IDs to fetch specific records (max 200).
permission_scopestring- Filter to audiences you own vs. audiences shared with the account (default OWNER).one of
OWNERSHARED qstring- Search query matching against the audience name (1-255 chars).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted records (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_do_not_reach_listsList the do-not-reach lists in an ads accountRead-onlyList Do Not Reach Lists
List the do-not-reach lists in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
countinteger- Number of records to return per page (default 200, max 1000).
cursorstring- Pagination cursor from a previous response.
do_not_reach_list_idsstring- Comma-separated do-not-reach list IDs to fetch specific records (max 200).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted records (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_funding_instrumentsList funding instruments (payment sources) for an ads accountRead-onlyList Funding Instruments
List funding instruments (payment sources) for an ads account
Inputs
account_idstringrequired- The ID of the ads account.
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
funding_instrument_idsstring- Comma-separated funding instrument IDs to fetch specific records (max 200).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted funding instruments (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_line_item_placementsList valid placement combinations per line item product typeRead-onlyList Line Item Placements
List valid placement combinations per line item product type
Inputs
product_typestring- Restrict placements to one product type.one of
MEDIAPROMOTED_ACCOUNTPROMOTED_TWEETS
xadsmcp_list_line_itemsList line items (ad groups) for an ads accountRead-onlyList Line Items
List line items (ad groups) for an ads account
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idsstring- Comma-separated campaign IDs to scope the line items to.
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
funding_instrument_idsstring- Comma-separated funding instrument IDs to scope the results to (max 200).
line_item_idsstring- Comma-separated line item IDs to fetch specific records (max 200).
qstring- Search by line item name (1-255 characters).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted line items in the response (default false).
with_draftboolean- Include line items of draft campaigns in the response (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_media_creativesList the media creatives in an ads accountRead-onlyList Media Creatives
List the media creatives in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idstring- Campaign ID to scope the media creatives to.
countinteger- Number of records to return per page (default 200, max 1000).
cursorstring- Pagination cursor from a previous response.
line_item_idsstring- Comma-separated line item IDs to scope the results to (max 200).
media_creative_idsstring- Comma-separated media creative IDs to fetch specific records (max 200).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted records (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_media_libraryList the media library objects in an ads accountRead-onlyList Media Library
List the media library objects in an ads account
Inputs
account_idstringrequired- The ID of the ads account.
countinteger- Number of records to return per page (default 20, max 50).
cursorstring- Pagination cursor from a previous response.
media_typestring- Restrict to one media type: IMAGE, VIDEO or GIF.
qstring- Search query matching against name, title, file_name and description.
xadsmcp_list_post_previewsGet rendered HTML previews for published or scheduled postsRead-onlyList Post Previews
Get rendered HTML previews for published or scheduled posts
Inputs
account_idstringrequired- The ID of the ads account.
tweet_idsstringrequired- Comma-separated post IDs (or scheduled post IDs, per tweet_type) to preview (max 200).
tweet_typestringrequired- Type of the IDs in tweet_ids.one of
PUBLISHEDDRAFTSCHEDULED user_idstring- Promotable user the posts belong to (defaults to the account's own user); needed when previewing ...
xadsmcp_list_promoted_postsList promoted posts (promoted tweets) for an ads accountRead-onlyList Promoted Posts
List promoted posts (promoted tweets) for an ads account
Inputs
account_idstringrequired- The ID of the ads account.
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
line_item_idsstring- Comma-separated line item IDs to scope the promoted posts to.
promoted_tweet_idsstring- Comma-separated promoted post IDs to fetch specific records (max 200).
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
with_deletedboolean- Include soft-deleted promoted posts in the response (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_list_targeting_criteriaList targeting criteria for an ads account's line itemsRead-onlyList Targeting Criteria
List targeting criteria for an ads account's line items
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idsstringrequired- Comma-separated line item IDs to scope the targeting criteria to (the legacy API requires this fi...
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
langstring- BCP-47 language code; adds a localized_name response attribute for localizable criteria.
sort_bystring- Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
targeting_criterion_idsstring- Comma-separated targeting criterion IDs to fetch specific records (max 200).
with_deletedboolean- Include soft-deleted targeting criteria (default false).
with_total_countboolean- Include the total_count response attribute (default false; exclusive with cursor).
xadsmcp_search_targeting_interestsSearch targetable interest categories by name.Read-onlySearch Targeting Interests
Search targetable interest categories by name. Use this to find the targeting_value IDs required by add_targeting_criterion for INTEREST-type criteria.
Inputs
countinteger- Number of records to return per page (1-1000).
cursorstring- Pagination cursor from a previous response.
qstring- Free-text interest name to search for, e.g. "motorsports". Omit to list interests unfiltered.
xadsmcp_search_targeting_locationsSearch targetable locations by name.Read-onlySearch Targeting Locations
Search targetable locations by name. Use this to find the targeting_value IDs required by add_targeting_criterion for LOCATION-type criteria.
Inputs
countinteger- Number of records to return per page (1-1000).
country_codestring- Two-letter ISO country code to scope results to, e.g. US.
cursorstring- Pagination cursor from a previous response.
location_typestring- Scope results to one location granularity.one of
COUNTRIESREGIONSMETROSCITIESPOSTAL_CODES qstring- Free-text location name to search for, e.g. "united states" or "london". Omit to list locations u...
xadsmcp_activate_campaignActivate a campaign (set entity_status=ACTIVE).WriteActivate Campaign
Activate a campaign (set entity_status=ACTIVE). This makes the campaign eligible to serve ads and SPEND REAL MONEY once its line items are also active. This is the only tool that can activate a campaign; confirm with the advertiser before calling it.
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idstringrequired- The ID of the campaign to activate.
xadsmcp_activate_line_itemActivate a line item (set entity_status=ACTIVE).WriteActivate Line Item
Activate a line item (set entity_status=ACTIVE). Once its parent campaign is also active, the line item becomes eligible to serve ads and SPEND REAL MONEY. This is the only tool that can activate a line item; confirm with the advertiser before calling it.
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idstringrequired- The ID of the line item to activate.
xadsmcp_add_targeting_criterionAdd one targeting criterion to a line item (call once per criterion).WriteAdd Targeting Criterion
Add one targeting criterion to a line item (call once per criterion). A line item with no criteria serves broad — that is allowed, not an error.
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idstringrequired- Line item to add the criterion to.
targeting_typestringrequired- Criterion type, e.g. LOCATION, INTEREST, BROAD_KEYWORD, PHRASE_KEYWORD, EXACT_KEYWORD, FOLLOWERS_...
targeting_valuestringrequired- Value for the type: a targeting ID for LOCATION/INTEREST (look up via targeting search), a user I...
operator_typestring- Comparison operator. Sent as EQ when omitted (ads-api requires it); NE negates (exclude).one of
EQNEGTELT
xadsmcp_batch_do_not_reach_list_usersAdd or remove hashed-email members of a do-not-reach list in batch (JSON array of operation objects)WriteBatch Do Not Reach List Users
Add or remove hashed-email members of a do-not-reach list in batch (JSON array of operation objects)
Inputs
account_idstringrequired- The ID of the ads account.
do_not_reach_list_idstringrequired- The ID of the do-not-reach list.
operationsarrayrequired- Array of operation objects adding or removing hashed-email members in one batch
xadsmcp_create_ad_postCompose a promoted-only ("nullcasted") post to use as an ad creative.WriteCreate Ad Post
Compose a promoted-only ("nullcasted") post to use as an ad creative. The post never appears on the author's profile or followers' timelines and spends nothing by itself — attach it to a line item with promote_post.
Inputs
account_idstringrequired- The ID of the ads account.
as_user_idstringrequired- User ID to post on behalf of (must be a promotable user of the account, e.g. the account's own ha...
card_uristring- Card URI to attach (e.g. a website card).
conversation_settingsstring- Who can reply to the post (default EVERYONE).one of
EVERYONEFOLLOWINGMENTIONED_USERS media_keysstring- Comma-separated media keys of pre-uploaded media to attach (required unless text is provided).
textstring- Post text (required unless media_keys is provided).
trim_userboolean- Return only the author's user ID instead of the full user object in the response (default false).
tweet_modestring- Response rendering mode (default compat).one of
compatextended video_ctastring- Call-to-action button on an attached video; set the target URL with video_cta_value.one of
VISIT_SITEWATCH_NOW video_cta_valuestring- Destination URL for the video_cta button; required when video_cta is set.
video_descriptionstring- Description shown under an attached video (1-200 characters).
video_titlestring- Title shown under an attached video (1-70 characters).
xadsmcp_create_app_event_tagCreate a mobile app conversion event tagWriteCreate App Event Tag
Create a mobile app conversion event tag
Inputs
account_idstringrequired- The ID of the ads account.
app_store_identifierstringrequired- App store identifier of the tracked app (numeric ID for iOS, package name for Android).
conversion_typestringrequired- Conversion event type.one of
ACHIEVEMENT_UNLOCKEDADDED_PAYMENT_INFOADD_TO_CARTADD_TO_WISHLISTCHECKOUT_INITIATEDCONTENT_VIEWINSTALLINVITELEVEL_ACHIEVEDLOGINPURCHASERATEDRESERVATIONRE_ENGAGESEARCHSHARESIGN_UPSPENT_CREDITSTUTORIAL_COMPLETEUPDATE os_typestringrequired- Operating system of the tracked app.one of
IOSANDROID provider_app_event_idstringrequired- The event's unique ID at the MACT provider.
provider_app_event_namestringrequired- The event's display name at the MACT provider.
deep_link_schemestring- Deep link URI scheme for the app, e.g. myapp://.
post_engagement_attribution_windowinteger- Post-engagement attribution window in days: 1, 7, 14, 30 or 90 (default 14).
post_view_attribution_windowinteger- Post-view attribution window in days: 0, 1, 7, 14, 30 or 90 (default 1).
retargeting_enabledboolean- Whether users who trigger this event are collected for retargeting (default true).
xadsmcp_create_app_listCreate an app list from app store identifiersWriteCreate App List
Create an app list from app store identifiers
Inputs
account_idstringrequired- The ID of the ads account.
app_store_identifiersstringrequired- Comma-separated app store identifiers (numeric IDs for iOS, package names for Android; max 500 ap...
namestringrequired- Display name for the app list.
xadsmcp_create_campaignCreate a campaign in an ads account.WriteCreate Campaign
Create a campaign in an ads account. The campaign is ALWAYS created with entity_status PAUSED — it cannot serve or spend until explicitly activated with activate_campaign. Campaigns are always created with budget_optimization LINE_ITEM (the only mode ads-api still supports), so budgets are NOT set here: set daily_budget_amount_local_micro on each line item via create_line_item. Schedule (start_time/end_time) and pacing (standard_delivery) also live on line items, not campaigns, in ads-api v12.
Inputs
account_idstringrequired- The ID of the ads account.
funding_instrument_idstringrequired- Funding instrument to bill this campaign to (from list_funding_instruments; must have able_to_fun...
namestringrequired- Campaign name (1-255 characters).
purchase_order_numberstring- Booking reference / PO number carried onto invoices for invoice-billed accounts (max 50 characters).
xadsmcp_create_cardCreate a card from a JSON components payload.WriteCreate Card
Create a card from a JSON components payload. Cards are immutable through this API (there is no update tool) — to change a card, create a new one and promote a new post that uses the new card_uri.
Inputs
account_idstringrequired- The ID of the ads account.
componentsarray- Card component objects, rendered top to bottom.
namestring- Card name.
xadsmcp_create_custom_audienceCreate a placeholder custom audience (populate it via the users endpoint)WriteCreate Custom Audience
Create a placeholder custom audience (populate it via the users endpoint)
Inputs
account_idstringrequired- The ID of the ads account.
namestringrequired- Display name for the audience.
descriptionstring- Optional free-text description of the audience.
xadsmcp_create_do_not_reach_listCreate a do-not-reach list (populate it via the batch users endpoint)WriteCreate Do Not Reach List
Create a do-not-reach list (populate it via the batch users endpoint)
Inputs
account_idstringrequired- The ID of the ads account.
descriptionstring- Free-text description of the list (max 100 chars).
xadsmcp_create_line_itemCreate a line item (ad group) under a campaign.WriteCreate Line Item
Create a line item (ad group) under a campaign. The line item is ALWAYS created with entity_status PAUSED — it cannot serve or spend until explicitly activated with activate_line_item. For website conversion campaigns, set goal=WEBSITE_CONVERSIONS and primary_web_event_tag to a web event tag (pixel) id from list_web_event_tags.
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idstringrequired- Campaign to create the line item under.
daily_budget_amount_local_microintegerrequired- Daily budget for this line item (ad group) in micros of the account currency (e.g. 50000000 = $50...
objectivestringrequired- Campaign objective for this line item.one of
APP_ENGAGEMENTSAPP_INSTALLSENGAGEMENTSFOLLOWERSPREROLL_VIEWSREACHVIDEO_VIEWSWEBSITE_CLICKS placementsstringrequired- Comma-separated placements, e.g. ALL_ON_TWITTER or TWITTER_TIMELINE,TWITTER_PROFILE. Valid values...
start_timestringrequired- Line item start time (ISO 8601, e.g. 2026-08-01T00:00:00Z). ads-api requires it on every new line...
advertiser_domainstring- Website domain of the advertiser (no protocol), e.g. x.com; required when placements includes PUB...
android_app_store_identifierstring- Google Play package name of the promoted app, e.g. com.example.app; for APP_INSTALLS / APP_ENGAGE...
audience_expansionstring- Audience expansion level. EXPANDED is what Ads Manager calls Optimized Targeting: serving may ext...one of
BROADDEFINEDEXPANDED bid_amount_local_microinteger- Bid in micros of the account currency; only with bid_strategy MAX or TARGET.
bid_strategystring- Bidding strategy. AUTO (default) needs no bid amount; MAX/TARGET require bid_amount_local_micro.one of
AUTOMAXTARGET categoriesstring- Comma-separated IAB content category IDs for the advertiser, e.g. IAB3-1,IAB19 (see list_iab_cate...
duration_in_daysinteger- Window over which frequency_cap applies (1, 7 or 30 days); set together with frequency_cap.
end_timestring- Line item end time (ISO 8601). Omit for no end.
frequency_capinteger- Maximum times an ad can be delivered to a user within duration_in_days; only for REACH, ENGAGEMEN...
goalstring- Optimization goal (e.g. ENGAGEMENT, LINK_CLICKS, SITE_VISITS, WEBSITE_CONVERSIONS, FOLLOWERS, APP...
ios_app_store_identifierstring- Numeric Apple App Store ID of the promoted app, e.g. 333903271; for APP_INSTALLS / APP_ENGAGEMENT...
namestring- Line item name (1-255 characters).
pay_bystring- Unit to pay by. Only settable for APP_INSTALLS (APP_CLICK or APP_INSTALL) and REACH (IMPRESSION) ...one of
APP_CLICKAPP_INSTALLENGAGEMENTFOLLOWIMPRESSIONLINK_CLICKVIEWVIEW_3S_100PCTVIEW_6SVIDEO_START primary_web_event_tagstring- Website conversion tag (pixel) id, required when goal=WEBSITE_CONVERSIONS; see list_web_event_tags.
product_typestring- Promoted product type. ads-api requires it on every new line item; sent as PROMOTED_TWEETS (post-...one of
PROMOTED_TWEETSPROMOTED_ACCOUNTMEDIA standard_deliveryboolean- true (default) paces spend evenly through the day; false spends as fast as possible (accelerated ...
total_budget_amount_local_microinteger- Line item total budget in micros of the account currency.
xadsmcp_create_media_creativeAssociate a media library object with a line item as a media creativeWriteCreate Media Creative
Associate a media library object with a line item as a media creative
Inputs
account_idstringrequired- The ID of the ads account.
account_media_idstring- Account media entity to promote (the account_media id, not a media_key). Required by the legacy API.
landing_urlstring- URL the user is directed to; required for preroll and image app download creatives.
line_item_idstring- Line item to associate the media with. Required by the legacy API.
xadsmcp_create_media_library_itemRegister an existing media key as a named item in the account's media library.WriteCreate Media Library Item
Register an existing media key as a named item in the account's media library. Use list_media_library to see media already registered to the account.
Inputs
account_idstringrequired- The ID of the ads account.
descriptionstring- Video description, shown under the video. Videos only.
file_namestring- Media file name (1-255 characters).
media_keystring- Media key of an existing media asset (e.g. 13_875943225764098048). Required by the legacy API.
namestring- Media asset name, shown in campaign setup UIs (1-100 characters).
poster_media_keystring- Media key of an uploaded image to use as the video poster frame. Videos only.
titlestring- Video title, shown on the video itself. Videos only.
xadsmcp_create_tracking_tagAssociate a tracking tag with a line itemWriteCreate Tracking Tag
Associate a tracking tag with a line item
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idstringrequired- The line item to associate the tracking tag with.
tracking_tag_typestringrequired- Tracking tag type; currently only IMPRESSION_TAG is supported.one of
IMPRESSION_TAG tracking_tag_urlstringrequired- The tracking tag URL supplied by the tracking partner.
xadsmcp_create_web_event_tagCreate a website conversion event tag (pixel); the returned id can be set as a line item's primary_web_event_tagWriteCreate Web Event Tag
Create a website conversion event tag (pixel); the returned id can be set as a line item's primary_web_event_tag
Inputs
account_idstringrequired- The ID of the ads account.
click_windowinteger- Post-click attribution window in days: 1, 7, 14, 30, 60 or 90. Required by the legacy API.
namestring- Conversion event name, shown in campaign setup UIs. Required by the legacy API.
retargeting_enabledboolean- Whether users who trigger this tag are collected for retargeting. Required by the legacy API.
typestring- Conversion type: SITE_VISIT, PURCHASE, DOWNLOAD, SIGN_UP or CUSTOM. Required by the legacy API.
view_through_windowinteger- Post-view window in days: 0, 1, 7, 14, 30, 60 or 90; max click_window. Required by the legacy API.
xadsmcp_promote_postAttach post(s) to a line item as its ad creative(s).WritePromote Post
Attach post(s) to a line item as its ad creative(s). Promoted posts have no entity_status of their own — they cannot serve while the parent line item or campaign is paused. The response carries each post's approval_status (ads enter review before serving).
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idstringrequired- Line item to attach the post(s) to.
tweet_idsstringrequired- Comma-separated post (tweet) IDs to promote (from list_account_posts or create_ad_post).
xadsmcp_update_campaignRename a campaign or pause it (entity_status=PAUSED).WriteUpdate Campaign
Rename a campaign or pause it (entity_status=PAUSED). This tool can pause but CANNOT activate — use activate_campaign to make a campaign eligible to spend. Budgets and schedule live on line items in ads-api v12: use update_line_item to change them.
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
campaign_idstringrequired- The ID of the campaign to update.
entity_statusstring- Only PAUSED is accepted (pauses the campaign). Activation is a separate explicit action via activ...one of
PAUSED funding_instrument_idstring- Move the campaign to a different funding instrument (from list_funding_instruments; must have abl...
namestring- New campaign name (1-255 characters).
purchase_order_numberstring- New booking reference / PO number carried onto invoices for invoice-billed accounts (max 50 chara...
standard_deliveryboolean- true paces spend evenly through the day; false spends as fast as possible (accelerated delivery).
xadsmcp_update_custom_audienceUpdate a custom audience's metadata (e.g.WriteUpdate Custom Audience
Update a custom audience's metadata (e.g. name)
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
custom_audience_idstringrequired- The ID of the custom audience.
descriptionstring- New free-text description of the audience.
namestring- New display name for the audience.
xadsmcp_update_line_itemUpdate a line item's bid, budget, name, schedule, placements, goal, pacing, audience expansion (set audience_expansion=EXPANDED to turn on Optimized Targeting) or entity_status.WriteUpdate Line Item
Update a line item's bid, budget, name, schedule, placements, goal, pacing, audience expansion (set audience_expansion=EXPANDED to turn on Optimized Targeting) or entity_status. Set entity_status=PAUSED to pause this ad group; pausing is only possible here, and activate_line_item is the only way to make it eligible to spend again.
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
line_item_idstringrequired- The ID of the line item to update.
advertiser_domainstring- New website domain of the advertiser (no protocol); required when placements includes PUBLISHER_N...
android_app_store_identifierstring- New Google Play package name of the promoted app, e.g. com.example.app.
audience_expansionstring- New audience expansion level; EXPANDED turns on what Ads Manager calls Optimized Targeting (off b...one of
BROADDEFINEDEXPANDED bid_amount_local_microinteger- New bid in micros of the account currency; only with bid_strategy MAX or TARGET.
bid_strategystring- New bidding strategy.one of
AUTOMAXTARGET categoriesstring- New comma-separated IAB content category IDs, e.g. IAB3-1,IAB19 (see list_iab_categories).
daily_budget_amount_local_microinteger- New line item daily budget in micros.
duration_in_daysinteger- New frequency_cap window (1, 7 or 30 days); set together with frequency_cap.
end_timestring- New end time (ISO 8601).
entity_statusstring- Set PAUSED to pause this ad group (the only pause path). Resume with activate_line_item.one of
PAUSED frequency_capinteger- New maximum times an ad can be delivered to a user within duration_in_days.
goalstring- New optimization goal (e.g. ENGAGEMENT, LINK_CLICKS, SITE_VISITS, WEBSITE_CONVERSIONS, FOLLOWERS,...
ios_app_store_identifierstring- New numeric Apple App Store ID of the promoted app, e.g. 333903271.
namestring- New line item name (1-255 characters).
pay_bystring- New unit to pay by. Only settable for APP_INSTALLS (APP_CLICK or APP_INSTALL) and REACH (IMPRESSI...one of
APP_CLICKAPP_INSTALLENGAGEMENTFOLLOWIMPRESSIONLINK_CLICKVIEWVIEW_3S_100PCTVIEW_6SVIDEO_START placementsstring- New comma-separated placements, e.g. ALL_ON_TWITTER or TWITTER_TIMELINE,TWITTER_PROFILE. Valid va...
primary_web_event_tagstring- New website conversion tag (pixel) id; see list_web_event_tags.
standard_deliveryboolean- true paces spend evenly through the day; false spends as fast as possible (accelerated delivery, ...
start_timestring- New start time (ISO 8601).
total_budget_amount_local_microinteger- New line item total budget in micros.
xadsmcp_update_media_library_itemUpdate a media library object's metadata (e.g.WriteUpdate Media Library Item
Update a media library object's metadata (e.g. name, title, description)
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
media_keystringrequired- The media key of the media library item.
descriptionstring- Video description, shown under the video. Videos only.
file_namestring- Media file name (1-255 characters).
namestring- Media asset name, shown in campaign setup UIs (1-100 characters).
poster_media_keystring- Media key of an uploaded image to use as the video poster frame. Videos only.
titlestring- Video title, shown on the video itself. Videos only.
xadsmcp_update_tracking_tagUpdate a tracking tag's URLWriteUpdate Tracking Tag
Update a tracking tag's URL
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
tracking_tag_idstringrequired- The ID of the tracking tag.
tracking_tag_urlstringrequired- The new tracking tag URL supplied by the tracking partner.
xadsmcp_update_web_event_tagUpdate a website conversion event tagWriteUpdate Web Event Tag
Update a website conversion event tag
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
web_event_tag_idstringrequired- The ID of the web event tag.
click_windowinteger- Post-click attribution window in days: 1, 7, 14, 30, 60 or 90.
namestring- Conversion event name, shown in campaign setup UIs.
retargeting_enabledboolean- Whether users who trigger this tag are collected for retargeting.
typestring- Conversion type.one of
SITE_VISITPURCHASEDOWNLOADSIGN_UPCUSTOM view_through_windowinteger- Post-view window in days: 0, 1, 7, 14, 30, 60 or 90; max click_window.
xadsmcp_delete_account_mediaDelete an account media object from an ads accountDestructiveDelete Account Media
Delete an account media object from an ads account
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
account_media_idstringrequired- The ID of the account media item.
xadsmcp_delete_app_event_tagDelete a mobile app conversion event tagDestructiveDelete App Event Tag
Delete a mobile app conversion event tag
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
app_event_tag_idstringrequired- The ID of the app event tag.
xadsmcp_delete_app_listDelete an app list from an ads accountDestructiveDelete App List
Delete an app list from an ads account
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
app_list_idstringrequired- The ID of the app list.
xadsmcp_delete_cardDelete a card from an ads account.DestructiveDelete Card
Delete a card from an ads account. Deleting a card that a live promoted post references leaves that post's card dangling (posts are immutable) — to swap a live ad's card, create the new card, create a new ad post with its card_uri, promote it, then pause the old ad before deleting the old card.
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
card_idstringrequired- The ID of the card.
xadsmcp_delete_custom_audienceDelete a custom audience from an ads accountDestructiveDelete Custom Audience
Delete a custom audience from an ads account
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
custom_audience_idstringrequired- The ID of the custom audience.
xadsmcp_delete_do_not_reach_listDelete a do-not-reach list from an ads accountDestructiveDelete Do Not Reach List
Delete a do-not-reach list from an ads account
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
do_not_reach_list_idstringrequired- The ID of the do-not-reach list.
xadsmcp_delete_media_creativeRemove a media creative from its line itemDestructiveDelete Media Creative
Remove a media creative from its line item
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
media_creative_idstringrequired- The ID of the media creative.
xadsmcp_delete_media_library_itemDelete a media library object from an ads accountDestructiveDelete Media Library Item
Delete a media library object from an ads account
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
media_keystringrequired- The media key of the media library item.
xadsmcp_delete_tracking_tagRemove a tracking tag from its line itemDestructiveDelete Tracking Tag
Remove a tracking tag from its line item
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
tracking_tag_idstringrequired- The ID of the tracking tag.
xadsmcp_delete_web_event_tagDelete a website conversion event tagDestructiveDelete Web Event Tag
Delete a website conversion event tag
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
web_event_tag_idstringrequired- The ID of the web event tag.
xadsmcp_remove_targetingRemove a targeting criterion from its line item (undo a targeting mistake).DestructiveRemove Targeting
Remove a targeting criterion from its line item (undo a targeting mistake). Criterion IDs come from list_targeting_criteria or the add response.
- Idempotent
Inputs
account_idstringrequired- The ID of the ads account.
targeting_criterion_idstringrequired- The ID of the targeting criterion.
No tools match.