> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Scores and metrics

> GEO score, scoreboard, timeseries, SEO dashboard, and page evaluation.

These routes expose the persisted score snapshots, the engine scoreboard, metric time series, the SEO dashboard, and on-demand page evaluation.

## Endpoints

| Method | Path                                             | Scope          | Description                        |
| ------ | ------------------------------------------------ | -------------- | ---------------------------------- |
| GET    | `/api/v1/workspaces/{workspace}/score`           | `metrics:read` | GEO score with component breakdown |
| GET    | `/api/v1/w/{brand}/score`                        | `metrics:read` | Compact brand route for GEO score  |
| GET    | `/api/v1/workspaces/{workspace}/scoreboard`      | `metrics:read` | Scoreboard                         |
| GET    | `/api/v1/workspaces/{workspace}/timeseries`      | `metrics:read` | Metric timeseries                  |
| GET    | `/api/v1/w/{brand}/timeseries`                   | `metrics:read` | Compact brand route for timeseries |
| GET    | `/api/v1/workspaces/{workspace}/metrics`         | `metrics:read` | Workspace metrics overview         |
| GET    | `/api/v1/workspaces/{workspace}/seo`             | `metrics:read` | SEO dashboard                      |
| POST   | `/api/v1/workspaces/{workspace}/seo`             | `runs:write`   | Refresh SEO dashboard (metered)    |
| GET    | `/api/v1/workspaces/{workspace}/page-evaluation` | `reports:read` | List page evaluations (latest 20)  |
| POST   | `/api/v1/workspaces/{workspace}/page-evaluation` | `runs:write`   | Start a page evaluation job        |

Note the scope asymmetry: the POST variants (`seo` refresh, `page-evaluation` start) need `runs:write`, not `metrics:read`.

## GEO score

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/score
```

Response:

```json theme={null}
{
  "score": 62,
  "version": "geo-score-v1",
  "components": {
    "visibility": { "weight": 0.25, "value": 58 },
    "relativeSov": { "weight": 0.35, "value": 65 },
    "position": { "weight": 0.15, "value": 70 },
    "sentiment": { "weight": 0.10, "value": 55 },
    "volume": { "weight": 0.15, "value": 50 }
  },
  "missingComponents": [],
  "date": "2026-08-10"
}
```

Add a `date` query parameter to get a historical snapshot:

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://ai-cmo.dev/api/v1/workspaces/{workspace}/score?date=2026-07-01"
```

### Compact brand route

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/w/{workspace}/score
```

## Scoreboard

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/scoreboard
```

Returns the brand and its competitors with their scores for comparison.

## Timeseries

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://ai-cmo.dev/api/v1/workspaces/{workspace}/timeseries?engine=composite&range=28d"
```

Query parameters:

<ParamField name="engine" type="string" default="composite" optional>
  Any engine identifier.
</ParamField>

<ParamField name="range" type="string" default="28d" optional>
  One of `7d`, `28d`, `all`.
</ParamField>

### Compact brand route

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://ai-cmo.dev/api/v1/w/{workspace}/timeseries?range=all"
```

## Metrics overview

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/metrics
```

## SEO dashboard

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/seo
```

Returns deterministic SEO and GEO scores, insights, and technical evidence.

### Refresh SEO

```bash theme={null}
curl -X POST https://ai-cmo.dev/api/v1/workspaces/{workspace}/seo \
  -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Returns (202) a job envelope. This is a metered operation — credits are required.

## Page evaluation

The GET endpoint returns the latest 20 evaluations.

```bash theme={null}
curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/page-evaluation
```

### Start a page evaluation

```bash theme={null}
curl -X POST https://ai-cmo.dev/api/v1/workspaces/{workspace}/page-evaluation \
  -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://{workspace}.com/about"}'
```

Returns (202) a job status.