AI Visibility runs

AI Visibility runs test how AI platforms answer prompts about a target entity.

One probe means one prompt sent to one platform for one target entity.

Tools

Tool	Purpose	Scope
create_sleepwalker_visibility_run	Queue a persisted AI Visibility run.	visibility:runs:create
cancel_sleepwalker_visibility_run	Cancel a run’s queued probes and release their credits.	visibility:runs:create
list_sleepwalker_visibility_models	List selectable AI models per platform, with prices.	runs:read
list_sleepwalker_visibility_runs	List direct AI Visibility runs.	runs:read
get_sleepwalker_visibility_run_status	Poll one run and optionally include results.	runs:read
get_sleepwalker_prompt_response	Fetch one probe’s full response and citations.	runs:read

create_sleepwalker_visibility_run

Use this when the user wants reportable probe results, not just prompt ideas.

Inputs

Input	Type	Required	Notes
url	string	Yes	Target URL.
target_entity	string	Yes	Brand, product, or entity to detect.
prompts	string[]	Conditional	Prompt list for matrix mode.
platforms	string[]	Conditional	Platform list for matrix mode. Canonical values are recommended, but common labels such as ChatGPT, Perplexity AI, Grok, and Google Gemini are accepted.
models	object	No	Matrix-mode per-platform model overrides, e.g. {"openai": "latest"}. See Model Selection.
probes	object[]	Conditional	Explicit probe rows (each may set model).
competitors	string[]	No	Competitor names to detect.
language	string	No	Defaults to en.
country	string	No	Defaults to US.
idempotency_key	string	No	Retry-safe key.

Send either:

• prompts and platforms, or
• probes.

Matrix Mode

Use matrix mode when the same target entity and locale apply to every prompt/platform combination.

Example user request:

Run these 10 AI Visibility prompts for Sleepwalker across the supported platforms.

The agent should call create_sleepwalker_visibility_run once with a prompt list and platform list. It should not submit dozens or hundreds of independent one-off tool calls.

Explicit Probes

Use explicit probes when each row needs different metadata.

Each probe can include:

Field	Required	Notes
prompt	Yes	Prompt text.
platform	Yes	Supported platform value or common platform label.
model	No	Pin the AI model (a model id or the keyword latest/prior/default). See Model Selection.
language	No	Probe language.
country	No	Probe market.
target_entity	No	Overrides top-level target entity.

Model Selection

Every platform runs its default model unless another one is chosen, and every model (defaults included) has its own per-probe price. Pick one either way:

• Matrix mode: pass a models map, e.g. {"openai": "latest", "perplexity": "sonar-pro"}.
• Explicit probes: set model on individual probes.

Values are a model id from list_sleepwalker_visibility_models or a role keyword: latest (current flagship), prior (previous generation), default. Keywords resolve to the platform’s current model at creation time; pin an exact id when a study depends on a specific version.

Each non-default model has its own per-probe price (it varies by model, not just tier), so call list_sleepwalker_visibility_models and sum credits_per_probe before quoting cost. Do not assume a flat rate. Invalid selections fail before any credits are reserved.

Response Shape

{
  "run_id": "6a75b22b-...",
  "status": "queued",
  "estimated_credits": "20.00",
  "reserved_credits": "20.00",
  "probe_count": 20,
  "queued_probe_count": 20,
  "skipped_probe_count": 0,
  "next_action": {
    "version": 1,
    "type": "poll_status",
    "tool": "get_sleepwalker_visibility_run_status",
    "arguments": {
      "run_id": "6a75b22b-...",
      "include_probes": true,
      "include_results": false
    },
    "poll_after_seconds": 15
  }
}

next_action tells MCP clients what to do next. For queued or running work, poll the status tool instead of creating another run.

Partial Queueing

If the account has enough credits for only part of a requested run, Sleepwalker can queue the funded probes and mark the rest as skipped.

The user can still inspect the probes that ran.

Example:

{
  "status": "partially_queued",
  "probe_count": 100,
  "queued_probe_count": 37,
  "skipped_probe_count": 63,
  "skipped_reason": "insufficient_credits"
}

Polling

After queueing a run, use:

get_sleepwalker_visibility_run_status

Inputs:

Input	Type	Required	Notes
run_id	string	Yes	Run returned by create.
include_probes	boolean	No	Defaults to true.
include_results	boolean	No	Defaults to false.
results_offset	integer	No	With include_results, skip this many results (paging).
results_limit	integer	No	With include_results, return at most this many results.

Poll every 10 to 30 seconds. For large runs, read compact status first, then page results with results_offset/results_limit, or fetch a single answer with get_sleepwalker_prompt_response. The summary always covers the full run.

Completed runs include a compact summary with mention_rate, overall_score, and overall_band. For AI Visibility, overall_score is the mention rate across successful probes.

When a compact status response is complete, next_action points back to get_sleepwalker_visibility_run_status with include_results: true so the client can fetch full response and citation evidence only when needed.

Credits

A queued probe costs its model’s own credits_per_probe (from list_sleepwalker_visibility_models); platform defaults range from 1 to 6 credits. A run’s reserved credits are the sum of its probes’ individual prices.

Examples:

Request	Probes	Credits
5 prompts x 4 platforms, all defaults	20	20
30 prompts x 1 platform, default	30	30
10 prompts, one platform pinned to a model priced 6 credits	10	60

Cancelling a Run

Stop a run that turned out bigger or more expensive than intended with:

cancel_sleepwalker_visibility_run

Pass the run_id of a direct-URL run (created with create_sleepwalker_visibility_run; saved-test runs cannot be cancelled). Probes no worker has picked up never run and their reserved credits return to the account; probes already claimed by a worker finish and settle normally, and completed results stay available. While in-flight probes are draining, the response reports billing_pending: true and the remaining release normally happens when the last one finishes; if the run later looks stuck without progress (for example after a worker crash), cancel again to force the remainder out. The call is idempotent: repeating it, or cancelling a finished run, changes nothing.

Agents should confirm with the user before cancelling, then poll get_sleepwalker_visibility_run_status until the run is terminal; the released amount equals reserved credits minus settled credits.

Example Prompts

Create an AI Visibility run for Sleepwalker with these prompts across the supported platforms, then poll until complete.

Cancel visibility run 6a75b22b, I picked the wrong model.

Check whether Sleepwalker is mentioned for "best AI visibility tools for SEO teams" on one platform.