Get Tracking Changes

GEThttps://api.boringmarketing.com/track/brands/{brand_id}/changes

Computes the difference between the most recent snapshot and the snapshot at or before a given since time. Returns structured deltas: ranking improvements, ranking declines, citation gains, citation losses.

Requires at least one prior snapshot from POST /track/brands/{brand_id}/snapshot.

Path parameters

brand_idstringrequired

The brand UUID.

Query parameters

sincestringrequired

ISO 8601 datetime. The endpoint finds the most recent snapshot at or before this time and diffs the latest snapshot against it.

Response

{
  "brand_id": "ea502f67-338b-47e4-a245-5c4eea8bd8d2",
  "from_snapshot": {
    "snapshot_id": "snap-1",
    "created_at": "2026-03-07T10:00:00Z"
  },
  "to_snapshot": {
    "snapshot_id": "snap-2",
    "created_at": "2026-04-07T10:00:00Z"
  },
  "rankings": {
    "improvements": [
      { "keyword": "ai marketing tools", "from": 14, "to": 6, "delta": 8 }
    ],
    "declines": [
      { "keyword": "marketing automation", "from": 4, "to": 9, "delta": -5 }
    ],
    "new": [
      { "keyword": "ai content workflow", "to": 11 }
    ],
    "lost": []
  },
  "citations": {
    "chat_gpt": { "from": 18, "to": 24, "delta": 6 },
    "google": { "from": 8, "to": 10, "delta": 2 }
  }
}

Returns 404 if there are no snapshots, or 422 if since cannot be parsed as ISO 8601.

Example

curl -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/track/brands/$BRAND_ID/changes?since=2026-03-07T10:00:00Z"

Use this on a schedule to drive the 7/30/90-day milestone observations. For example: on publish, call POST /track/brands/{id}/snapshot; 7 days later, capture another snapshot and call this endpoint with ?since=<publish_timestamp> to get the exact 7-day delta; then report it via POST /track/outcomes/report with event_type: "observed_7d".