Quickstart - ai-cmo.dev

This guide walks through the full measurement lifecycle in one continuous example. Replace gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with a real API key from your workspace.

Authenticate

export NM_KEY="gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export NM_WS="your-workspace-slug"

List workspaces

curl -H "Authorization: Bearer $NM_KEY" \
     https://ai-cmo.dev/api/v1/workspaces

Response:

[
  {
    "id": "acme",
    "displayName": "Acme Corp",
    "plan": "free",
    "role": "owner",
    "domains": ["acme.com"]
  }
]

Every workspace list returns the full array; there is no cursor pagination.

Read the GEO score

curl -H "Authorization: Bearer $NM_KEY" \
  "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"
}

The score is 0–100. Five weighted components: visibility (0.25), relativeSov (0.35), position (0.15), sentiment (0.10), volume (0.15). Missing components are reported in missingComponents and the remaining weights renormalize.

Start a measurement run

curl -X POST "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs" \
  -H "Authorization: Bearer $NM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "standard"}'

Response (202):

{
  "id": "run_abc123",
  "brand": "acme",
  "kind": "measurement",
  "status": "running",
  "progress": { "completedCalls": 0, "totalCalls": 150, "percent": 0, "source": "calls" },
  "startedAt": "2026-08-10T10:00:00Z",
  "finishedAt": null,
  "pid": 12345,
  "logPath": "/tmp/geo/run_acme_20260810_100000.log",
  "lastLines": []
}

Four presets: standard (150 active prompts), lite (50), smoke (2), and exa (150). The run starts if credits are sufficient, no other measurement is running for this brand, and the pipeline worker cap has not been reached.Optionally include an idempotencyKey to make the start safe for retries:

curl -X POST "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs" \
  -H "Authorization: Bearer $NM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "standard", "idempotencyKey": "start-run-20260810-01"}'

Poll the job

curl -H "Authorization: Bearer $NM_KEY" \
  "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs/{id}"

Eventually returns:

{
  "id": "run_abc123",
  "brand": "acme",
  "kind": "measurement",
  "status": "succeeded",
  "progress": { "completedCalls": 150, "totalCalls": 150, "percent": 100, "source": "calls" },
  "startedAt": "2026-08-10T10:00:00Z",
  "finishedAt": "2026-08-10T10:15:00Z",
  "pid": 12345,
  "logPath": "/tmp/geo/run_acme_20260810_100000.log",
  "lastLines": ["Measurement complete"]
}

Read the run detail

curl -H "Authorization: Bearer $NM_KEY" \
  "https://ai-cmo.dev/api/v1/workspaces/{workspace}/runs/{id}/detail"

The detail response groups results by engine, with brand mentions, citations, sentiments, and visible prompt results per engine.

Common errors

Scenario	HTTP	Code
Wrong or missing key	401	`invalid_key`
Insufficient credits	402	`insufficient_credits`
Workspace mismatch	404	`workspace_not_found`
Measurement already running	409	`job_already_running`
Pipeline at capacity	429	`pipeline_capacity_reached`

​Common errors

Common errors