Reports by URL

Finds saved tests matching a URL and returns compact recent run summaries.

Use this endpoint when an integration knows a page URL but does not know whether the account already has saved Sleepwalker results for it.

Endpoint

GET /v1/reports/by-url

Authentication

Header	Required	Value
Authorization	Yes	Bearer sw_api_live_...

Required scope:

runs:read

Query Parameters

Parameter	Type	Required	Description
url	string	Yes	URL to look up.
test_type	string	No	Filter to ai_citations or content_intelligence.
days	integer	No	Lookback window. Clamped between 1 and 365. Defaults to 90.
limit	integer	No	Recent run summaries per matched test. Clamped between 1 and 20. Defaults to 5.

Example Request

curl -s "https://api.sleepwalker.ai/v1/reports/by-url?url=https%3A%2F%2Fwww.sleepwalker.ai&limit=3" \
  -H "Authorization: Bearer sw_api_live_..."

The same request in Python and JavaScript:

Python

import requests

resp = requests.get(
    "https://api.sleepwalker.ai/v1/reports/by-url",
    headers={"Authorization": "Bearer sw_api_live_..."},
    params={"url": "https://www.sleepwalker.ai", "limit": 3},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const params = new URLSearchParams({ url: "https://www.sleepwalker.ai", limit: "3" });
const resp = await fetch(`https://api.sleepwalker.ai/v1/reports/by-url?${params}`, {
  headers: { Authorization: "Bearer sw_api_live_..." },
});
const data = await resp.json();
console.log(data);

Response

{
  "url": "https://www.sleepwalker.ai",
  "test_type": null,
  "days": 90,
  "limit": 3,
  "match_count": 1,
  "matches": [
    {
      "test": {
        "id": "47d0f0e2-...",
        "name": "Homepage",
        "brand_name": "Sleepwalker",
        "test_type": "ai_citations",
        "url": "https://www.sleepwalker.ai"
      },
      "runs": [
        {
          "run_id": "6a75b22b-...",
          "test_id": "47d0f0e2-...",
          "test_type": "ai_citations",
          "status": "completed",
          "created_at": "2026-06-04T09:00:00Z",
          "overall_score": 75,
          "overall_band": "Good"
        }
      ]
    }
  ],
  "excluded_test_types": ["technical_monitoring"]
}

Notes

• The response is compact. Full saved-test analysis remains available in the Sleepwalker app.
• A saved Content Intelligence run_id can be passed to GET /v1/content-intelligence/runs/{run_id} for compact compatibility status. A saved AI Visibility test run ID is not a direct visibility-run ID and cannot be passed to /v1/visibility/runs/{run_id}.
• URL matching uses Sleepwalker’s normalized URL lookup.
• This endpoint reads saved-test reports. For direct infrastructure runs, use the run-specific list/status endpoints.

Errors

Status	Meaning
400	Empty/invalid URL or unsupported test_type.
401	Missing or invalid API key.
403	API key is missing runs:read.
422	url is missing, or a query parameter has the wrong type.

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