Get visibility run

Returns status and optional compact results for one direct AI Visibility run.

Endpoint

GET /v1/visibility/runs/{run_id}

Authentication

Header	Required	Value
`Authorization`	Yes	`Bearer sw_api_live_...`

Required scope:

runs:read

Path Parameters

Parameter	Type	Description
`run_id`	string	AI Visibility run UUID.

Query Parameters

Parameter	Type	Required	Description
`include_probes`	boolean	No	Include compact probe rows. Defaults to `false`.
`include_results`	boolean	No	Include compact `ca_result` payload. Defaults to `false`.

Example Request

curl -s "https://api.sleepwalker.ai/v1/visibility/runs/6a75b22b-0000-0000-0000-000000000000?include_probes=true&include_results=true" \
  -H "Authorization: Bearer sw_api_live_..."

The same request in Python and JavaScript:

import requests

run_id = "6a75b22b-0000-0000-0000-000000000000"
resp = requests.get(
    f"https://api.sleepwalker.ai/v1/visibility/runs/{run_id}",
    headers={"Authorization": "Bearer sw_api_live_..."},
    params={"include_probes": "true", "include_results": "true"},
)
resp.raise_for_status()
print(resp.json())

const runId = "6a75b22b-0000-0000-0000-000000000000";
const resp = await fetch(
  `https://api.sleepwalker.ai/v1/visibility/runs/${runId}?include_probes=true&include_results=true`,
  { headers: { Authorization: "Bearer sw_api_live_..." } },
);
const data = await resp.json();
console.log(data);

Response

{
  "run_id": "6a75b22b-...",
  "action_decision_id": "act_...",
  "status": "completed",
  "source": "api",
  "created_at": "2026-06-10T12:30:00Z",
  "started_at": "2026-06-10T12:30:05Z",
  "completed_at": "2026-06-10T12:31:10Z",
  "url": "https://www.sleepwalker.ai",
  "target_entity": "Sleepwalker",
  "language": "en",
  "country": "US",
  "requested_probe_count": 4,
  "queued_probe_count": 4,
  "running_probe_count": 0,
  "succeeded_probe_count": 4,
  "errored_probe_count": 0,
  "cancelled_probe_count": 0,
  "estimated_credits": "4.00",
  "reserved_credits": "0.00",
  "settled_credits": "4.00",
  "summary": {
    "brand_mentions": 2,
    "citation_mentions": 1
  },
  "ca_result": {
    "platforms": {}
  },
  "probes": [
    {
      "prompt": "What are the best AI visibility tools for SEO teams?",
      "platform": "perplexity",
      "status": "succeeded"
    }
  ]
}

Summary Counts

Field	Meaning
`brand_mentions`	Number of successful probe responses where the target entity was mentioned in the answer body.
`citation_mentions`	Number of successful probe responses where the target entity, URL, or domain appeared in cited sources.

Probe counters are reported separately so a zero-mention run can be distinguished from a run that failed to execute.

Polling Pattern

create run -> queued
poll status -> running
poll status -> completed
fetch include_results=true when terminal

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
`401`	Missing or invalid API key.
`403`	API key is missing `runs:read`, or this action is unavailable.
`404`	Run was not found or does not belong to the authenticated user.