spotifyApr 22, 2026

Building a Natural Language Interface to the Spotify Ads API with Claude Code Plugins | Spotify Engineering (opens in new tab)

The post describes an open-source Claude Code plugin that lets users manage Spotify advertising campaigns through natural-language requests. It translates high-level intent into validated, multi-step Spotify Ads API calls, handling targeting lookups, budget conversions, entity dependencies, and missing information. The authors favor a Markdown- and CLI-based design over MCP because it keeps the system transparent, lightweight, customizable, and grounded in Spotify’s OpenAPI specification. ## Natural-Language Campaign Creation - Users can request campaigns conversationally, such as creating an audio campaign targeting a specific age range and location with a daily budget. - The agent orchestrates the campaign lifecycle: - Creates the campaign. - Creates an ad set with targeting and budget. - Creates the ad and attaches creative assets. - It handles implementation details automatically: - Looks up geographic targeting IDs. - Converts dollar amounts into API micro-units. - Validates audience size. - Passes entity IDs between dependent API calls. - Prompts for missing required information. ## Claude Code Plugin Architecture - **Skills** provide slash commands, with each command defined in Markdown alongside its endpoints, request formats, and output behavior. - **Agents** interpret freeform requests and decompose them into the necessary API operations. - **Hooks** intercept tool calls to refresh OAuth tokens and inject HTTP headers. - **Settings** store local user configuration, including credentials, ad accounts, and environment preferences. - Because all components are human-readable Markdown, the plugin has no compilation, bundling, or package-management step. - API behavior can often be corrected by updating documentation or instructions rather than changing compiled code. ## CLI and OpenAPI Instead of MCP - The authors avoided MCP because the Spotify Ads API has more than 30 resource types and complex nested schemas. - Defining every endpoint as an MCP tool would create a large static registry and consume context even when most tools were irrelevant. - The plugin loads only the API documentation needed for a particular task. - API calls are issued as visible `curl` commands, allowing users to inspect, copy, modify, and reproduce them. - Spotify’s roughly 8,600-line OpenAPI v3 specification serves as the single source of truth. - Updating one bundled specification file is simpler than maintaining a separate translation into MCP schemas. ## Domain-Specific Agent Behavior - The request-builder agent is defined in `agents/spotify-ads-request-builder.md`. - It teaches the model Spotify-specific conversions, including: - Dollar values to micro-amounts. - Natural-language dates to ISO 8601. - Platform names to API enum values. - It performs multi-step orchestration for campaign, ad set, and ad creation. - It resolves locations such as “Connecticut” through geo-targeting search endpoints and builds the required `geo_targets` structure. - It performs pre-flight audience estimates to ensure targeting meets minimum size requirements. - It is designed to control execution carefully and validate requests before making changes that could affect advertising budgets. ## Practical Implication The plugin demonstrates that a large advertising API can be made approachable without hiding its mechanics. A Markdown-based Claude Code integration, backed by the official OpenAPI specification and transparent CLI requests, offers a practical balance between natural-language convenience, developer control, auditability, and maintainability.

database-designpythonnlpclaude-code+4

spotifyApr 6, 2026

Background Coding Agents: Supercharging Downstream Consumer Dataset Migrations (Honk, Part 4) | Spotify Engineering (opens in new tab)

Spotify used its Honk background coding agent with Backstage and Fleet Management to automate migrations from two deprecated datasets to new versions. The effort targeted roughly 1,800 downstream pipelines and produced 240 automated pull requests, potentially saving about 10 engineering weeks. The experience showed that agents perform best when repositories follow standardized patterns, prompts contain precise technical context, and automated testing is available. ## The Challenge of Large-Scale Dataset Migrations - Two heavily used datasets needed replacement to support new dimensions and features. - The datasets had approximately 1,800 direct downstream pipelines and affected thousands more indirectly. - Migrations spanned three frameworks: - BigQuery Runner - dbt - Scala-based Scio - Manual migration was estimated to require around 10 engineering weeks within a six-month deadline. ## Using Backstage to Identify Consumers - Backstage’s endpoint lineage pages revealed downstream dataset consumers. - Its Codesearch plugin located relevant repositories across Spotify’s GitHub Enterprise environment. - The Fleetshift plugin used those results to organize and orchestrate repository migrations. - Backstage also provided a centralized view for tracking progress and opening generated pull requests. ## Context Engineering for Honk - Honk needed detailed, self-contained prompts because it could not access external documentation, dataset schemas, MCPs, or custom Claude skills during execution. - Scio was excluded because its flexible, inconsistent implementations made it difficult to describe all migration cases in one reliable prompt. - BigQuery Runner and dbt were more standardized, making them better candidates for automation. - An initial prompt based on a human migration guide was insufficient and caused incorrect assumptions about field mappings. - Explicit mapping tables in the context file significantly improved results. - Prompts also specified cases where fields should not be migrated automatically. - Honk left those fields unchanged. - It added comments linking to human migration guidance for later review. ## Testing and Automated Pull Requests - BigQuery Runner and dbt repositories generally lacked build-time unit tests. - As a result, Honk could not automatically verify and correct its changes, one of its key capabilities. - Downstream teams had to manually test the generated pull requests before merging. - Despite this limitation, the team successfully created 240 automated migration PRs. - Fleetshift’s Backstage interface simplified monitoring, troubleshooting, repository navigation, and communication with owning teams. ## Lessons for Future Agent-Driven Maintenance - Large-scale automation depends on standardizing frameworks and data practices across repositories. - Consistent testing and validation requirements are essential so agents can verify their own changes. - Future Honk functionality will allow agents to gather context from sources such as JIRA tickets and documentation before editing code. - Better context gathering should reduce the need for exhaustive prompt files and improve migration quality. Spotify’s experience suggests that background coding agents can substantially reduce migration toil, but their effectiveness depends on disciplined standardization, explicit migration rules, and strong automated testing.

database-designdata-pipelinebigquerydbt+4

spotifyFeb 19, 2026

Inside the Archive: The Tech Behind Your 2025 Wrapped Highlights | Spotify Engineering (opens in new tab)

Spotify’s 2025 Wrapped Archive identified up to five remarkable listening days for each eligible user and turned them into personalized, LLM-generated stories. A distributed pipeline, carefully designed prompts, model distillation, and massive-scale pre-generation made it possible to create roughly 1.4 billion reports before launch. The system prioritized factual grounding, creative consistency, safety, and reliable parallel storage. ## Identifying Remarkable Listening Days - Spotify used a priority-ordered set of heuristics to evaluate each user’s full year of listening. - Straightforward categories included: - Biggest Music Listening Day - Biggest Podcast Listening Day - Biggest Discovery Day, based on first-time artists - Biggest Top Artist Day - Biggest Top Genre Day - More nuanced categories detected: - Nostalgic listening and throwback-heavy sessions - Unusual listening patterns that differed from a user’s typical taste - Contextual dates such as birthdays and New Year’s Day - Candidate days were ranked by narrative potential and statistical strength, reducing hundreds of millions of events to as many as five standout days per user. - A distributed data pipeline aggregated the results and stored listening data in object storage. - Messaging queues then moved each user’s data asynchronously into report generation. ## Prompt Engineering for Reliable Stories - Spotify spent more than three months iterating on prompts and evaluating edge cases. - The system prompt established: - Traceability to real listening behavior - A witty, sincere, and quietly playful tone - Safety constraints excluding references to drugs, alcohol, sex, violence, and offensive language - User prompts supplied: - Detailed daily listening logs - Precomputed statistics, since LLMs are unreliable at arithmetic - Overall Wrapped data - The remarkable-day category - Previously generated reports to reduce repetition - The user’s country for appropriate spelling and vocabulary - Outputs were improved through prototype comparisons, LLM-based judging, human review, and feedback from creative, technical, and safety teams. ## Distilling the Model for Scale - Larger frontier models produced strong results during prototyping but were too expensive for more than a billion generations. - Spotify generated high-quality reference outputs and curated them into a reviewed “gold” dataset. - A smaller, faster production model was fine-tuned on that dataset. - Direct Preference Optimization (DPO), based on curated human A/B evaluations, further aligned the smaller model with the preferred output style. - The resulting model achieved preference performance comparable to the larger baseline. ## Generating 1.4 Billion Reports - Approximately 350 million users were eligible, with up to five reports each. - Spotify pre-generated about 1.4 billion reports before Wrapped launch. - The system sustained thousands of model requests per second over several days. - After remarkable days were computed, snapshots were published to a pub/sub queue. - Reports were generated sequentially per user so earlier reports could inform later ones and prevent repetition. - Real-time dashboards tracked throughput, reliability, errors, and projected completion time. - The generation engine ran continuously for four days, followed by checks for missing reports, inconsistencies, and necessary re-generation. ## Designing Storage for Concurrent Writes - Completed reports were stored in a distributed, column-oriented key-value database optimized for high-throughput writes. - Each user occupied a single row, with separate columns representing completed remarkable days. - Instead of maintaining a serialized list—which could cause race conditions during read-modify-write operations—each date received its own column qualifier in `YYYYMMDD` format. - Independent reports could therefore be written concurrently to separate cells without locks or coordination. - Report content was written first, followed by lightweight metadata marking the report complete. - This ordering prevented the system from exposing a completion marker before the underlying report was safely stored. ## Practical Conclusion Building Wrapped Archive required treating creative AI generation as a large-scale production system: ground outputs in structured data, use smaller specialized models when volume demands it, evaluate continuously, and design storage schemas that make concurrency safe by default.

database-designllmprompt-engineeringhigh-throughput+4