---
title: Get Tracking Changes
api: GET /track/brands/{brand_id}/changes
description: "Compute the delta between the latest tracking snapshot and an earlier one. Returns structured ranking and citation deltas."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

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

<ParamField path="brand_id" type="string" required>
  The brand UUID.
</ParamField>

## Query parameters

<ParamField query="since" type="string" required>
  ISO 8601 datetime. The endpoint finds the most recent snapshot at or before this time and diffs the latest snapshot against it.
</ParamField>

## Response

```json
{
  "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

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

<Tip>
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"`.
</Tip>