API reference

Runs

Create a tracking run, read its status, and fetch parsed results with distributions.

POST /v1/runs

field	type	notes
prompt	string	required, max 500 chars
surfaces	string[]	required, one or more surface ids
country	string	ISO 3166-1 alpha-2, default US
language	string	ISO 639-1, defaults to the country's primary language
samples	integer	1–50, default 10
brands	string[]	optional, brands to score explicitly
webhook_url	string	optional, receives the completed payload
project_id	string	required for workspace keys

curl -X POST https://api.nostimates.com/v1/runs \
  -H "Authorization: Bearer $NOSTIMATES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "best CRM for B2B sales",
    "surfaces": ["google_ai_overviews", "chatgpt", "perplexity"],
    "country": "US",
    "language": "en",
    "samples": 10,
    "webhook_url": "https://your-app.example.com/hooks/nostimates"
  }'

GET /v1/runs/{run_id}

Returns the run with a status of queued, running, complete or failed. Completed runs include the full parsed payload.

{
  "run_id": "run_9f3c21ab",
  "prompt": "best CRM for B2B sales",
  "surface": "google_ai_overviews",
  "country": "US",
  "language": "en",
  "samples": 10,
  "collected_at": "2026-08-03T06:12:44Z",
  "brands": [
    { "name": "HubSpot",   "mention_rate": 0.90, "ci95": { "low": 0.60, "high": 0.98 }, "avg_position": 1.4 },
    { "name": "Salesforce","mention_rate": 0.70, "ci95": { "low": 0.40, "high": 0.89 }, "avg_position": 2.1 },
    { "name": "Pipedrive", "mention_rate": 0.30, "ci95": { "low": 0.11, "high": 0.60 }, "avg_position": 3.8 }
  ],
  "citations": [
    { "url": "https://www.g2.com/categories/crm", "position": 1, "sample_frequency": 0.90 },
    { "url": "https://www.hubspot.com/products/crm", "position": 2, "sample_frequency": 0.70 }
  ],
  "extraction": { "success": true, "parser_version": "aio-2026.07.3" }
}

GET /v1/runs

Lists runs for a project, filterable by surface, prompt, date range and status. Cursor-paginated at 100 per page.