Set up one Monday-morning scheduled job that fans out rank checks across every workspace, alerts on meaningful drops, and optionally triggers a stale-content refresh on impacted pages.

A Monday-morning rank report across every client brand in your portfolio, with alerts on meaningful drops. One scheduled job, one webhook, one client report.


Outcome	Per-workspace rank snapshot every Monday + automated alerts on drops of 5+ positions
Time	~5 min setup; runs in 2–8 min depending on portfolio size
Cost	~0.5 credits per keyword per check
Prereqs	Agency master key, workspaces with keywords already labeled, DataForSEO connected (or BYOK)

What it does

workspaces.bulk_action (scheduled weekly:mon:09:00)
  ↓ fans out one child invocation per workspace
  ├── ws_acme  → agent.invoke(skill: rank_monitor)
  ├── ws_beta  → agent.invoke(skill: rank_monitor)
  └── ... (one per workspace)
↓
on drop detected:
  rank.dropped webhook fires
  ↓
your portal / Slack notifies the account manager
↓
optional: refresh_stale skill fires on the affected content

Step 1 — Set up the scheduled rank check

curl -X POST https://api.citationbench.com/v1/workspaces/bulk-action \
  -H "Authorization: Bearer sk_live_agency_***" \
  -d '{
    "action":     "agent.invoke",
    "workspaces": "all",
    "schedule":   "weekly:mon:09:00",
    "config": {
      "skill": "rank_monitor",
      "input": {
        "scope":   { "intent": ["PURCHASE", "ALTERNATIVE"] },
        "alertOn": { "drop": 5, "lostFromTop10": true }
      }
    }
  }'

Response includes the parent invocation that orchestrates the schedule. Edit or pause at any time.

Step 2 — Filter to what actually matters

The scope filter controls which keywords get checked per workspace. Common patterns:

{ "intent": ["PURCHASE", "ALTERNATIVE"] }
{ "priority": ["CRITICAL", "HIGH"] }
{ "pillar": "pricing" }
{ "hasContent": true }
{ "tag": "client-priority" }

Combine for the agency's curated list:

{
  "intent": ["PURCHASE"],
  "priority": ["CRITICAL", "HIGH"],
  "hasContent": true
}

Step 3 — Wire alerts to your portal

curl -X POST https://api.citationbench.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_agency_***" \
  -d '{
    "url":    "https://hooks.our-portal.com/rank-alerts",
    "events": ["rank.dropped"]
  }'

Payload:

{
  "workspaceId": "ws_acme",
  "keyword": "project management for engineering teams",
  "previousPosition": 7,
  "currentPosition": 14,
  "delta": -7,
  "alertTriggered": "drop_5_plus"
}

Step 4 — Optional: auto-trigger refresh on drops

Chain rank_monitor to refresh_stale:

curl -X POST .../v1/agent/invoke -d '{
  "skill": "rank_monitor",
  "input": {
    "scope":   { "intent": ["PURCHASE"] },
    "alertOn": { "drop": 5 },
    "onDrop":  { "invokeSkill": "refresh_stale" }
  }
}'

When a drop is detected, the agent spawns a refresh_stale invocation on the affected content. The draft refresh queues at WAITING_APPROVAL for the client.

Step 5 — Build the agency dashboard

# Snapshot across all workspaces
curl -X POST .../v1/workspaces/bulk-action -d '{
  "action":     "distribute.track_rank.snapshot",
  "workspaces": "all",
  "config":     { "scope": { "priority": ["CRITICAL", "HIGH"] } }
}'

Render as a per-workspace table; track deltas week over week.

One-shot script

#!/usr/bin/env bash
set -euo pipefail

KEY="${CITATIONBENCH_API_KEY:?}"
BASE="https://api.citationbench.com/v1"

# 1. Schedule the weekly run
curl -sf -X POST $BASE/workspaces/bulk-action \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "action":     "agent.invoke",
    "workspaces": "all",
    "schedule":   "weekly:mon:09:00",
    "config": {
      "skill": "rank_monitor",
      "input": {
        "scope":   { "intent": ["PURCHASE", "ALTERNATIVE"], "priority": ["CRITICAL", "HIGH"] },
        "alertOn": { "drop": 5, "lostFromTop10": true },
        "onDrop":  { "invokeSkill": "refresh_stale" }
      }
    }
  }'

# 2. Register the alert webhook
curl -sf -X POST $BASE/webhooks \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "url":    "https://hooks.our-portal.com/rank-alerts",
    "events": ["rank.dropped"]
  }'

echo "Weekly rank monitoring + auto-refresh active across all workspaces."

Gotchas

Cost matters at scale. A portfolio of 30 workspaces × 50 keywords × 0.5 credits = 750 credits/week. Budget for it or filter aggressively via scope.
DataForSEO rate limits. Heavy parallel rank checks can throttle. The bulk action paces itself; bursting via direct invocations can hit limits.
Time zone. The cron string is UTC. For Monday 9am Eastern use weekly:mon:14:00.
Alert spam. Drop thresholds of 1–2 positions create noise. 5+ is the recommended floor.

API: Agent · invoke
API: Workspaces (bulk action)
API: Research · keyword
Concept: Agent
Playbook: Refresh stale content on rank drops

Weekly rank checks across every client in your agency portfolio