Building with AI

Manage Spotify ad campaigns using natural language. The Spotify Ads API Plugin works across three agentic coding platforms with the same skills, same API, and one codebase.

Whether you're building a full campaign from a text description, bulk-managing ad sets across markets, or pulling performance reports — the plugin translates your intent into Spotify Ads API calls.

Getting Started

Claude Code

Install the Spotify Ads API plugin directly from your terminal:


_10claude plugin i spotify-ads-api

OpenAI Codex

Install from the Codex plugin marketplace:


_10codex plugin marketplace add spotify/ads-agentic-tools

Gemini CLI

Install via the Gemini extensions system:


_10gemini extensions install https://github.com/spotify/ads-agentic-tools

Prerequisites

Before installing the plugin on any platform, make sure you have:

An agentic coding platform: Claude Code, OpenAI Codex, or Gemini CLI
A Spotify Developer account with an ads-enabled application — create one at developer.spotify.com
A Spotify Ads ad account ID — sign up at Ads Manager
Redirect URI configured to http://127.0.0.1:8080/callback
API terms accepted at adsmanager.spotify.com/api-terms using your client ID
Python 3.8+ (optional — required only for local OAuth helper scripts)

Configuration

After installing the plugin, run the configuration skill to set up authentication:


_10/spotify-ads-api:configure

The configure skill supports three authentication methods:

Method	Description	Best for
OAuth 2.0 (recommended)	Browser-based login with automatic token refresh	Most users — tokens auto-refresh via macOS Keychain
Manual OAuth	Complete the OAuth flow manually without the Python helper	Environments where Python 3.8+ is not available
Direct Token (Legacy)	Paste an existing access token directly	CI/CD pipelines, quick testing, or non-interactive environments

On macOS, your client secret is stored in the system Keychain. OAuth tokens auto-refresh when they expire — no manual token management required.

Available Skills

The plugin includes 13 skills that cover the full campaign lifecycle:

Skill	Description
`configure`	Set up authentication and ad account credentials
`campaigns`	List, create, get, or update campaigns
`ads`	List, create, get, or update ad sets and ads
`build-campaign`	Parses your description and creates the full campaign hierarchy as drafts that you can validate and publish
`campaign-strategy`	Generate an API-ready campaign plan from a landing page, brand brief, or business goal
`drafts`	Create, validate, and publish draft campaigns, ad sets, and ads
`report`	Pull aggregate metrics, audience insights, or async CSV reports
`assets`	Upload and manage audio, video, and image creative assets
`dashboard`	Quick performance overview — impressions, spend, reach, clicks
`monitor`	Check campaign health — pacing, delivery issues, budget burn rate
`export`	Export campaign data to CSV for offline analysis
`bulk`	Batch operations — pause, resume, update budgets, swap creatives
`clone`	Duplicate campaigns or ad sets with optional modifications

Sample Prompts

These examples show what you can do with the plugin across any supported platform.

Build a full campaign from text

"Build an awareness campaign called Summer Beats targeting 18-34 year olds in the US, UK, and DE. $50/day budget, audio format, running July 1-31."

The build-campaign skill parses your description and creates the full campaign hierarchy as drafts — campaign, ad sets, and ads — that you can validate and publish.

Bulk multi-geo creation

"Create ad sets for US, UK, DE, FR, and AU with the same targeting but localized budgets: $50/day for US, £30/day for UK, €35/day for DE and FR, and A$40/day for AU."

Only available through the plugin — create geo-specific ad sets in one command instead of configuring each market individually.

Clone and modify

"Clone campaign 'Spring Launch Q2' into a new campaign called 'Summer Launch Q3', update the dates to August 1-31, and increase the budget by 20%."

The clone skill duplicates the full campaign hierarchy and applies your modifications in one step.

Conditional bulk actions

"Pause all ad sets that have spent more than 80% of their budget but delivered fewer than 50% of target impressions."

Only available through the plugin — apply conditional logic across ad sets based on performance thresholds.

Cross-campaign reporting

"Compare performance across my three active campaigns — show impressions, spend, CTR, and completion rate side by side for the last 7 days."

Pull and compare metrics across campaigns in a single query.

CSV report generation

"Generate a CSV report for campaign 'Brand Awareness Q2' broken down by day, including impressions, reach, frequency, spend, and CTR."

The report skill generates downloadable CSV files for offline analysis and stakeholder sharing.

Underpacing monitoring

"Check all active campaigns for underpacing — flag any that are below 80% of expected delivery."

The monitor skill analyzes delivery pacing and alerts you to campaigns that need attention.

Quick performance check

"How are my campaigns doing today?"

The dashboard skill provides a snapshot of all active campaigns — impressions, spend, reach, and clicks at a glance.

Release Notes

v1.6.0 — June 2026

Gemini CLI support: The plugin now works on all three major agentic coding platforms. On Gemini CLI, skills activate from natural language without requiring the /spotify-ads-api: prefix
Drafts skill: New drafts skill to create, validate, and publish draft campaigns, ad sets, and ads
Draft-first build-campaign: The build-campaign skill now defaults to a draft workflow — create, validate, then publish
Stricter validation: Improved input validation across all skills to catch errors before API calls

v1.0.0 — May 2026

Initial release with support for Claude Code — core campaign management, reporting, and asset skills
OAuth 2.0 authentication with automatic token refresh via macOS Keychain
One codebase powering all supported platforms

Open source: The plugin is available on GitHub at github.com/spotify/ads-agentic-tools under the Apache 2.0 license.