Campaigns vs Individual Scans

Campaigns schedule recurring scans across multiple locations and keywords. Individual scans are for one-off spot checks.

When to Use Each

Individual Scan Campaign
Best for One-time spot checks, ad hoc analysis Recurring monitoring, multi-location tracking
Scheduling Manual only One-time, daily, weekly, biweekly, monthly
Locations One per scan One or many
Keywords One per scan One or many
Report output Separate Scan, Competitor, Trend, Location, Keyword reports Consolidated Campaign Report (no separate Location/Keyword/Trend)
Credits Per scan Per scan within campaign (total checked against balance)

Campaign Lifecycle

Verify Locations

Locations must be in your Saved Locations before they can be added to a campaign. List existing locations with:

POST /v1/locations/

If a location is not yet saved, add it with POST /v2/locations/add first.

Create the Campaign

Endpoint: POST /v2/campaigns/create

Parameter Type Required Description
name string Yes Campaign name
placeId string Yes Place ID(s), comma-separated for multiple
keyword string Yes Keyword(s), comma-separated for multiple
gridSize enum Yes 3–21
radius string Yes 0.1–100
measurement enum Yes mi or km
frequency enum Yes one-time, daily, weekly, biweekly, monthly
startDate string Yes MM/DD/YYYY
startTime string Yes e.g., "9:00 AM"

Campaigns support grid sizes up to 21×21, larger than the 15×15 maximum for individual scans.

Monitor and Manage

  • Run manually: POST /v2/campaigns/run — trigger a campaign immediately
  • Pause: POST /v2/campaigns/pause — stop scheduled runs
  • Resume: POST /v2/campaigns/resume — restart after pause
  • Reactivate: POST /v2/campaigns/reactivate — restart after credit deactivation

Retrieve Results

List campaigns with a fieldmask to browse results:

POST /v1/campaigns/

Get a specific campaign report by its key:

POST /v1/campaigns/{report_key}

Report Consolidation

Campaign scans consolidate all data into the Campaign Report. Unlike individual scans:

  • No separate Location Reports are generated
  • No separate Keyword Reports are generated
  • No separate Trend Reports are generated
  • Scan Reports and Competitor Reports are still created per scan within the campaign
  • Scan reports include a campaign_key linking back to the parent campaign
  • Historical data (trending) is available within the Campaign Report itself

Fieldmask Recipes

Browsing Campaigns 
report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv,arp_move,atrp_move,solv_move
Campaign Report Detail 
report_key,name,status,locations,keywords,arp,atrp,solv,arp_move,atrp_move,solv_move,frequency,last_run,next_run

Running a campaign manually costs credits for every scan in the campaign (locations × keywords). Check your credit balance with POST /v2/account before triggering large campaigns. Never retry run-campaign — the campaign is already queued.

Next Steps