Scores and metrics - ai-cmo.dev

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

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

Response:

{
  "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:

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

Compact brand route

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

Scoreboard

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

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

Query parameters:

Compact brand route

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

Metrics overview

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

SEO dashboard

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

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.

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

Start a page evaluation

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.

​Endpoints

​GEO score

​Compact brand route

​Scoreboard

​Timeseries

​Compact brand route

​Metrics overview

​SEO dashboard

​Refresh SEO

​Page evaluation

​Start a page evaluation

Endpoints

GEO score

Compact brand route

Scoreboard

Timeseries

Compact brand route

Metrics overview

SEO dashboard

Refresh SEO

Page evaluation

Start a page evaluation