Tool Reference

list_simulations

List recent AI simulation sessions.

List recent AI simulation sessions — probes of how configured AI engines answer queries about your brand.

Parameters

Parameter Type Required Description
brandId string No Filter to a specific brand (UUID or exact name). Omit for company-wide history.
limit number No Maximum number of simulations to return (default: 20, max: 100)
offset number No Number of simulations to skip for pagination (default: 0)

Example Request

curl -X POST https://socialcrm.com/api/mcp-app \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "list_simulations",
      "arguments": {
        "limit": 5
      }
    }
  }'

Example Response

Parsed from result.content[0].text:

[
  {
    "id": "3b3a8b77-9c0c-4ef4-b96d-b23ef91d8b15",
    "platform": "ChatGPT",
    "brandName": "Ace Auto Repair",
    "query": "best brake repair shop near Dallas",
    "status": "completed",
    "score": 85,
    "mode": "visibility",
    "createdAt": "2026-08-09T15:30:00.000Z"
  },
  {
    "id": "9c2f1d40-6a1b-4c8e-9f21-0d5f6f2ab001",
    "platform": "Claude",
    "brandName": "Ace Auto Repair",
    "query": null,
    "status": "completed",
    "score": 62,
    "mode": "readiness",
    "createdAt": "2026-08-08T10:15:00.000Z"
  }
]

Output Schema

Returns an array of simulation summary objects:

Field Type Description
id string Simulation session UUID
platform string AI platform probed (e.g., "ChatGPT", "Claude", "Gemini")
brandName string | null Brand profile name associated with the simulation
query string | null The custom query for ad-hoc (Playground) runs. null for standard runs, which probe three fixed query types — per-query detail lives on the session's results.
status string "pending", "running", "completed", or "failed"
score number | null Overall accuracy score for the run (0–100). null while pending or when evaluation could not be scored.
mode string | null "visibility" (organic probe — the platform answered cold), "readiness" (grounded — brand content supplied), or "both".
createdAt string ISO 8601 timestamp

Notes

  • Simulations are created through the dashboard's AI Simulator and Playground (POST /api/simulations).
  • visibility mode measures what the platform actually says about your brand today; readiness measures the best answer your content could support. The gap between them is the optimization opportunity.
  • Results are ordered by most recent first.