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.
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.

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.
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:

Python

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())

JavaScript

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

Each AI Visibility probe costs 1 credit.

Examples:

Request	Probes	Credits
5 prompts x 4 platforms	20	20
30 prompts x 1 platform	30	30
100 prompts x 4 platforms	400	400

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, missing target entity, or invalid probe matrix.
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.