---
title: Check Outcomes
api: POST /brands/{brand_id}/outcomes/check
description: "Run milestone checks for any outcomes overdue for 7/30/90-day observation. Batches DataForSEO calls to minimize cost."
---

> **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.

Scans all recorded outcomes for this brand and runs milestone checks for any that are overdue (i.e. past the 7/30/90-day interval since their `completed` event and not yet observed at that milestone). Batches DataForSEO calls internally to minimize API cost.

The results are persisted as `outcome_milestones` rows (one per observed milestone, upserted by `(outcome_id, milestone_days)`) and become visible on the next `GET /brands/{brand_id}/outcomes` read in the corresponding `observed_7d` / `observed_30d` / `observed_90d` slot. This is **not** the same as recording a new outcome event via `POST /track/outcomes/report` — milestone observations are child rows attached to an existing outcome.

## Path parameters

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

## Request body

None.

## Response

```json
{
  "brand_id": "brand-uuid",
  "checked": 5,
  "milestones": [
    {
      "outcome_id": "outcome-uuid",
      "keyword": "ai marketing tools",
      "milestone_days": 7,
      "rank": 14,
      "citations_total": 2
    }
  ]
}
```

| Field | Description |
|---|---|
| `checked` | Number of overdue milestones that were observed and persisted on this call. `0` when nothing was overdue. |
| `milestones` | One entry per milestone observation written this run. `outcome_id` correlates back to the row in `GET /brands/{id}/outcomes`. |
| `error` | Only present on a hard failure (e.g. `"brand_not_found"`). When present, `checked` is `0` and `milestones` is `[]`. |

After this call, the new milestone observations are visible on the next `GET /brands/{id}/outcomes` read in the corresponding `observed_7d` / `observed_30d` / `observed_90d` slot.

## Example

```bash
curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  https://api.boringmarketing.com/brands/$BRAND_ID/outcomes/check
```

<Tip>
Run this on a daily or weekly cron. It's idempotent — calling it more often than milestone intervals simply does nothing for already-observed outcomes.
</Tip>