Scope3 Campaign API

​
Set up your agent

Sign up for Scope3 and get an API key. Our MCP server is at https://api.agentic.scope3.com/mcp and uses the HTTP Streaming transport mechanism. For authentication, add x-scope3-api-key: {scope3_api_key}.

​
Sample agent

If you don’t have an agent, download this Python script: 🐍 langchain-claude-agent.py This example shows how to:
  • Connect to the Scope3 MCP API using langchain-mcp-adapters
  • Create a react agent with Claude as the reasoning engine
  • Build an interactive chat interface for campaign management
Just install the dependencies, add your API keys to .env, and run the agent! 
uv init
uv add langchain-mcp-adapters langgraph langchain-anthropic python-dotenv

touch .env
echo "SCOPE3_API_KEY=scope3_...." >> .env
echo "GEMINI_API_KEY=..." >> .env

uv run langchain-claude-agent.py
If you use Claude Code or another coding agent, check out the quickstart for agents!

​
Steps your agent needs to do to set up a campaign

  1. Create a brand agent, which holds the goals and key objects for an advertiser
  2. Add creatives directly or connect a creative agent
  3. Use a prompt to set up a campaign
  4. Explore the tactics the campaign is using
  5. Monitor performance
Here’s what’s happening behind the scenes:

​
Create Brand Agent

Your brand agent acts as an advertiser account that owns all campaigns and assets. Brand agents have three identifiers that you can use to reference them across all of our APIs, which saves a lookup roundtrip or the need to cache our ID somewhere:
  • Internal Scope3 ID
  • Your ID, which we call this the external ID. For instance, if your naming scheme is ‘scope3-nike-us-aug2025-lightup-2823’, you could pass that into any tool and we will map it to this agent.
  • A nickname. For instance if you give the agent the nickname “Nike EMEA”, you could ask “what are all the campaigns live for the Nike EMEA agent” and send “Nike EMEA” into any of our MCP tools
To get started, let’s create a simple agent. User: Please create a Scope3 brand agent for Nike EMEA c/o Kinesso (which we call Nike), mapping to our internal advertiser ID abc-123. Their primary domain is nike.com. Agent: Call tool create_brand_agent with body: 
{
  "name": "Nike EMEA c/o Kinesso",
  "external_id": "abc-123",
  "nickname": "Nike",
  "advertiser_domains": ["nike.com"]
}
Scope3 create_brand_agent response 
{
  "success": true,
  "message": "Brand agent created successfully"
}

​
Add Creatives

Creatives can be added after the campaign is set up, but let’s do it now. Let’s assume we’re running a third-party tag for the purposes of this demo, but the platform also supports native, hosted, and custom formats too. Again, the platform supports external IDs and nicknames if helpful. User: OK, here are my ad tags for this campaign: Creative 1 <html>...</html> Creative 2 <html>...</html> Agent: Call tool create_creatives with body: 
[
  {
    "name": "Creative 1",
    "snippet": "<html>...</html>",
    "snippet_type": "html"
  },
  {
    "name": "Creative 2",
    "snippet": "<html>...</html>",
    "snippet_type": "html"
  }
]
Scope3 create_creatives response 
{
  "success": true,
  "message": "Two creatives created successfully"
}

​
Sales Agents (Automatic Access)

Your campaigns automatically have access to advertising inventory through Scope3’s sales agent relationships. No setup required! Optional: Register Your Own Sales Agent Account If you have a direct relationship with a sales agent, you can register your account to:
  • Pay them directly (Scope3 charges less for direct connections)
  • Use your negotiated terms and rates
  • Note that you will get invoiced separately by Scope3 for these campaigns, whereas for Scope3 accounts these fees are factored into media cost
User: We have a direct account with Scribd’s sales team Agent: Call tool sales_agents_register with body: 
{
  "name": "Scribd Direct", 
  "endpoint_url": "https://ads.scribd.com/adcp",
  "account_identifier": "nike-scribd-2024",
  "auth_config": {
    "api_key": "scribd_api_key_here"
  }
}
Scope3 sales_agents_register response 
{
  "success": true,
  "message": "Sales agent account registered successfully"
}
When you register your own sales agent account, you handle payments directly with that sales agent. Your account will override Scope3’s default relationship with that sales agent.

​
Set up the campaign

The “magic” of using an agentic API is that we don’t need to try to map all of the complex targeting fields across platforms because AI is very good at figuring out, for instance, that “US” and “USA” are the same thing - we don’t need a complex protocol spec for handling ISO country codes. We also don’t need to try to take a well-thought-out brief and map it to an audience or contextual taxonomy. Instead, we can send our brief to signals agents - which could include an internal agent that knows about our customer data - and let the agent recommend the best audiences for this brief. We could also manage this selection process with our own algorithm, or feed in sales data to score outcomes that would inform the Scope3 algorithm. There is a lot more to say about how campaigns work in the agentic context, but we’ll save that for later. For now, let’s write a simple brief and let the Scope3 engine recommend the best tactics for our brief. (to do - let’s add scoring and optimization to this example) User: Nike is looking for high school and college volleyball players for their new line of “Super Spike” shoes - the first indoor spikes. They think the target audience skews female, but recognize that volleyball parents are often called in to make these complex shoe purchases. They want to launch in the US in Q4 with a total budget of $250,000 running on premium display inventory. We will run creative 1 and creative 2 on this campaign. Agent: Call tool create_campaign with data: 
{
  "brand_agent": "Nike",
  "prompt": "Nike is looking for...",
  "nickname": "Super Spike Q4",
  "budget": {
    "total": 250000,
    "currency": "USD"
  },
  "start_utc": "2025-09-01 00:00:00",
  "end_utc": "2025-12-31 23:59:59",
  "creatives": ["creative 1", "creative 2"]
}
Scope3 create_creatives response 
{
  "success": true,
  "message": "Campaign created successfully"
}

​
Explore tactics

Tactics are a combination of inventory and signals that are executed in an actual media buy with a publisher. To execute a campaign, we need to:
  • Find inventory that could be a fit for our campaign
  • Find signals that could be a fit for our campaign
  • Build a candidate list of tactics that combine inventory and signals
  • Calculate how many tactics we can explore given our budget and measurement sensitivity
  • Select the initial set of tactics to try
  • Select a price point and daily budget for each tactic
As the campaign progresses:
  • Allocate more budget to the tactics that are working
  • Adjust price for tactics
and explore more tactics to replace those that aren’t Since we didn’t turn off the built-in algorithm, it will:
  • Send the Nike brief and our creative formats to each publisher using the AdCP get_products tool and get back a list of media products (which could include publisher data or optimization)
  • Send the Nike brief to any connected signals agents to see if any audience data might help find volleyball players or families
  • (to do - scoring details)
  • Select the initial tactics and prices based on heuristic and historical data
Let’s see the tactics that the algorithm has chosen… User: What are the tactics for the Super Spike Q4 campaign? Agent”: Call tool get_campaign_tactics with data: 
{
  "campaign": "Super Spike Q4"
}
Scope3: get_campaign_tactics response: 
{
  "tactics": [
    {"id": "asci82", "publisher": "Yahoo", "product": "Yahoo Sports - youth athletes", "daily_budget": 100, "cpm", 4.50},
    {"id": "8adai", "publisher": "Raptive", "product": "Sports network", "daily_budget": 100, "cpm": 2.50},
    {"id": "as822ns", "publisher": "Weather.com", "product": "run of network", "signal_provider": "Mastercard", "signal": "Volleyball shoe buyers", "daily_budget": 100, "cpm": 5.00}
  ]
}

​
Monitor Performance

Once the campaign launches, we can monitor performance in a few ways, from getting log-level data pushed to a cloud bucket, using the APIs to dump aggregated data into an analytics system, or simply asking how the campaign is doing. If we don’t specify a date range, the system will assume “lifetime to date”. User: How is Super Spike Q4 doing? Agent: Call tool get_campaign_summary: 
{
  "campaign": "Super Spike Q4"
}
Scope3: get_campaign_summary response: 
{
  "dateRange": {
    "start": "2024-12-01",
    "end": "2024-12-07"
  },
  "currency": "USD",
  "summary": {
    "spend": 12450.00,
    "impressions": 2100000,
    "averageCpm": 3.93
  },
  "insights": [
    {
      "type": "top_tactics_by_spend",
      "tactics": [
        ...
      ]
    }
  ]
}

​
🎉 Congratulations!

You’ve successfully:
  • ✅ Created your first brand agent
  • ✅ Added creatives
  • ✅ Launched a campaign
  • ✅ Explored optimization tactics
  • ✅ Monitored performance

​
Next steps

Some ideas for where to go from here:

​
Common Questions (to do)

Campaigns typically start delivering within 2-4 hours of launch. Initial optimization begins immediately, with meaningful performance data available within 24-48 hours.
While campaigns can start at 1,000,werecommend1,000, we recommend 10,000+ for campaigns where performance optimization is important. Higher budgets enable more effective machine learning.
Yes! All tools work conversationally with AI assistants. The natural language interface makes campaign management accessible to non-technical users.
Use the data export tools to push campaign data to your BI systems, or set up webhooks for real-time integration. We support all major analytics platforms.