Create visibility run

Queues a persisted AI Visibility run.

An AI Visibility run is made of probes. One probe is one prompt sent to one supported platform and market for one target entity.

Use this endpoint when you want results to be saved, billed, pollable, and visible in the Sleepwalker account.

Successful create requests return 200 OK with the queued run handle.

Endpoint

POST /v1/visibility/runs

Authentication

Header	Required	Value
`Authorization`	Yes	`Bearer sw_api_live_...`
`Content-Type`	Yes	`application/json`

Required scope:

visibility:runs:create

Use runs:read as well if the same key will poll the run.

Request Body

Field	Type	Required	Description
`url`	string	Yes	Target URL being evaluated.
`target_entity`	string	Yes	Brand, product, or entity to detect in responses.
`prompts`	string[]	Conditional	Prompt list for matrix mode.
`platforms`	string[]	Conditional	Platform list for matrix mode.
`probes`	object[]	Conditional	Explicit probe list. Use instead of `prompts` x `platforms` when each probe needs custom metadata.
`models`	object	No	Per-platform model overrides for matrix mode, for example `{"perplexity": "sonar-pro"}`. Platforms not listed use their default model. Not allowed together with `probes`.
`competitors`	string[]	No	Competitor names to detect in responses and summaries. Maximum 10.
`language`	string	No	Default language for matrix probes. Defaults to `en`.
`country`	string	No	Default country/market for matrix probes. Defaults to `US`.
`idempotency_key`	string	No	Retry-safe key. Maximum 160 characters.

You must provide either:

prompts and platforms, or
probes.

Supported platform values are listed in Enums → Supported Platforms. Statuses and code formats are listed in Enums. Visibility limits are listed in Limits.

Model Selection

Every platform runs its default model unless you select another one. List the selectable models per platform with List visibility models.

Matrix mode: pass a models map, for example "models": {"perplexity": "sonar-pro"}. Platforms without an entry keep their default.
Explicit probes: set model on individual probes.

Model values accept a catalog model id or one of the role keywords default, latest, prior (case-insensitive). Keywords resolve to the platform’s current model for that role at creation time: "models": {"openai": "latest"} always means the newest OpenAI model in the catalog, and the probe records the concrete model it ran on. The price follows the resolved model, including when a keyword resolves to the platform default.

Every model has its own per-probe price based on what it costs to run (platform defaults range from 1 to 6 credits): a premium flagship costs more than a budget model, and two models in the same tier can differ. List visibility models returns the exact credits_per_probe for every option; always price a run from that endpoint rather than assuming a fixed tier rate. Requests fail with 400 before any credits are reserved when the selection is invalid:

Error	Meaning
`unsupported_model`	The model is not selectable for that platform.
`model_platform_not_requested`	The `models` map names a platform that is not in `platforms`.
`duplicate_model_platform`	Two keys in `models` resolve to the same platform.
`model_required`	A `models` entry has an empty value. Omit the key to use the default.
`models_map_requires_prompt_platform_matrix`	`models` was combined with `probes`. Set `model` per probe instead.

Probe Object

Use probes when each row needs its own prompt/platform/locale/entity.

Field	Type	Required	Inherits from top level?	Description
`prompt`	string	Yes	No	Prompt to execute. Maximum 500 characters.
`platform`	string	Yes	No	One of the supported platform values.
`model`	string	No	No	Model to run this probe on. Defaults to the platform’s default model.
`language`	string	No	Yes	Prompt language. Defaults to top-level `language`, then `en`.
`country`	string	No	Yes	Market/country. Defaults to top-level `country`, then `US`.
`target_entity`	string	No	Yes	Brand, product, or entity to detect. Defaults to top-level `target_entity`.

Matrix Example

This creates 2 prompts x 2 platforms = 4 probes.

curl -s https://api.sleepwalker.ai/v1/visibility/runs \
  -H "Authorization: Bearer sw_api_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.sleepwalker.ai",
    "target_entity": "Sleepwalker",
    "prompts": [
      "What are the best AI visibility tools for SEO teams?",
      "Which tools track brand citations in AI search?"
    ],
    "platforms": ["perplexity", "openai"],
    "language": "en",
    "country": "US",
    "idempotency_key": "visibility-sleepwalker-2026-06-10"
  }'

The same request in Python and JavaScript:

import requests

resp = requests.post(
    "https://api.sleepwalker.ai/v1/visibility/runs",
    headers={"Authorization": "Bearer sw_api_live_..."},
    json={
        "url": "https://www.sleepwalker.ai",
        "target_entity": "Sleepwalker",
        "prompts": [
            "What are the best AI visibility tools for SEO teams?",
            "Which tools track brand citations in AI search?",
        ],
        "platforms": ["perplexity", "openai"],
        "language": "en",
        "country": "US",
        "idempotency_key": "visibility-sleepwalker-2026-06-10",
    },
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.sleepwalker.ai/v1/visibility/runs", {
  method: "POST",
  headers: {
    Authorization: "Bearer sw_api_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.sleepwalker.ai",
    target_entity: "Sleepwalker",
    prompts: [
      "What are the best AI visibility tools for SEO teams?",
      "Which tools track brand citations in AI search?",
    ],
    platforms: ["perplexity", "openai"],
    language: "en",
    country: "US",
    idempotency_key: "visibility-sleepwalker-2026-06-10",
  }),
});
const data = await resp.json();
console.log(data);

Explicit Probe Example

Use explicit probes when prompt, platform, locale, or entity varies per row.

curl -s https://api.sleepwalker.ai/v1/visibility/runs \
  -H "Authorization: Bearer sw_api_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.sleepwalker.ai",
    "target_entity": "Sleepwalker",
    "probes": [
      {
        "prompt": "What are the best AI visibility tools for SEO teams?",
        "platform": "perplexity",
        "language": "en",
        "country": "US",
        "target_entity": "Sleepwalker"
      },
      {
        "prompt": "Wat zijn goede AI visibility tools voor SEO teams?",
        "platform": "openai",
        "language": "nl",
        "country": "NL"
      }
    ],
    "idempotency_key": "visibility-explicit-2026-06-10"
  }'

Response

{
  "action_decision_id": "act_...",
  "run_id": "6a75b22b-...",
  "status": "queued",
  "estimated_credits": "4.00",
  "reserved_credits": "4.00",
  "probe_count": 4,
  "queued_probe_count": 4,
  "skipped_probe_count": 0,
  "skipped_reason": null,
  "prompt_count": 2,
  "platform_count": 2
}

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.

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

The queued probes remain accessible. Skipped probes are visible as not run because of insufficient credits.

See Credit Lifecycle for reservation, settlement, and release behavior.

Credits

Every probe costs its model’s own credits_per_probe from List visibility models; platform defaults range from 1 to 6 credits. Prices vary by model, not by tier.

Partial funding is applied in probe order: probes queue one by one until the next probe no longer fits the remaining balance.

Examples (using the sample prices above; check the live endpoint for current values):

Request	Probes	Credits
5 prompts x all 4 platform defaults (1 + 1 + 6 + 2 credits)	20	50
30 prompts x Perplexity on its 1-credit default	30	30
5 prompts x Perplexity default plus OpenAI `gpt-5.6-terra` (6 credits)	10	5 + 30 = 35
10 prompts on `gpt-5.6-sol` (15 cr)	10	150

Polling

Poll Get AI Visibility Run until status is completed, failed, or another terminal state. Sleepwalker does not send webhooks; polling is the supported way to detect completion.

Recommended polling interval: 10 to 30 seconds.

Most small runs complete within a few minutes. Larger runs depend on probe count and platform availability.

Errors

Status	Meaning
`400`	Invalid URL, whitespace-only target entity, or invalid probe/model combination.
`401`	Missing or invalid API key.
`402`	No probes can be queued because credits are insufficient.
`403`	API key is missing `visibility:runs:create`, or this action is unavailable.
`422`	Required fields are missing, have the wrong type, or violate a declared field bound.

API-key rate limits and temporary server errors are documented in Errors.