#GhostUser API

#Authentication

Every request must include your API key as a Bearer token in the Authorization header. Keys look like gu_live_xxx and are created in the dashboard under Account → API keys at ghostuser.io.

curl https://ghostuser.io/v1/runs \
  -H "Authorization: Bearer gu_live_xxx"

#Quickstart

Three steps: start a test, poll it, and read the result. Runs are asynchronous — a real run drives a live browser and can take a few minutes — so you start a run, then poll GET /v1/runs/{id} until status is done.

1. 1Start a run — POST /v1/runs with your URL. You get back a run id and status: "running".
2. 2Poll the run — GET /v1/runs/{id} every few seconds until status flips to done (or error).
3. 3Read the result — pull overall_score, counts, and the issues array. Open report_url for the full visual report.

# 1. Start a run
curl -X POST https://ghostuser.io/v1/runs \
  -H "Authorization: Bearer gu_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yourapp.com","tier":"economy"}'
# → { "id": "ab12cd34", "status": "running", ... }

# 2. Poll until status is "done"
curl https://ghostuser.io/v1/runs/ab12cd34 \
  -H "Authorization: Bearer gu_live_xxx"
# → { "id": "ab12cd34", "status": "done", "overall_score": 7.5, ... }

const BASE = "https://ghostuser.io/v1";
const headers = {
  "Authorization": "Bearer gu_live_xxx",
  "Content-Type": "application/json",
};

// 1. Start a run
const start = await fetch(`${BASE}/runs`, {
  method: "POST",
  headers,
  body: JSON.stringify({ url: "https://yourapp.com", tier: "economy" }),
});
const { id } = await start.json();

// 2. Poll until done
async function waitForRun(id) {
  while (true) {
    const run = await (await fetch(`${BASE}/runs/${id}`, { headers })).json();
    if (run.status === "done") return run;
    if (run.status === "error") throw new Error("run failed");
    await new Promise((r) => setTimeout(r, 5000)); // 5s
  }
}

// 3. Read the result
const report = await waitForRun(id);
console.log(report.overall_score, report.issues);

import time, requests

BASE = "https://ghostuser.io/v1"
headers = {"Authorization": "Bearer gu_live_xxx"}

# 1. Start a run
start = requests.post(
    f"{BASE}/runs",
    headers=headers,
    json={"url": "https://yourapp.com", "tier": "economy"},
)
run_id = start.json()["id"]

# 2. Poll until done
while True:
    run = requests.get(f"{BASE}/runs/{run_id}", headers=headers).json()
    if run["status"] == "done":
        break
    if run["status"] == "error":
        raise RuntimeError("run failed")
    time.sleep(5)

# 3. Read the result
print(run["overall_score"], run["issues"])

#Runs

A run is the core resource: one ghost-user test of one URL. Create a run to start a test, fetch a run to read its report, and list runs to see your recent history. A run moves through running → done (or error).

curl -X POST https://ghostuser.io/v1/runs \
  -H "Authorization: Bearer gu_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com",
    "tier": "economy",
    "personas": ["first_timer", "mobile_first_user"],
    "scenario": "test the signup flow"
  }'

{
  "id": "ab12cd34",
  "status": "running",
  "url": "https://yourapp.com",
  "tier": "economy",
  "created_at": "2026-06-23T14:00:00Z",
  "report_url": "https://ghostuser.io/report/ab12cd34"
}

curl https://ghostuser.io/v1/runs/ab12cd34 \
  -H "Authorization: Bearer gu_live_xxx"

{
  "id": "ab12cd34",
  "status": "done",
  "url": "https://yourapp.com",
  "tier": "economy",
  "created_at": "2026-06-23T14:00:00Z",
  "overall_score": 7.5,
  "counts": { "critical": 0, "major": 1, "minor": 2 },
  "num_ghosts": 2,
  "headline": "Solid core flow, but the signup CTA is easy to miss on mobile.",
  "issues": [
    {
      "severity": "major",
      "title": "Signup button is below the fold on mobile",
      "detail": "On a 375px viewport the primary CTA sits under three scrolls of copy.",
      "quote": "Wait, where do I actually sign up? I had to scroll forever.",
      "fix": "Pin a sticky 'Get started' button or move it above the fold on small screens."
    }
  ],
  "report_url": "https://ghostuser.io/report/ab12cd34"
}

curl https://ghostuser.io/v1/runs \
  -H "Authorization: Bearer gu_live_xxx"

{
  "runs": [
    {
      "id": "ab12cd34",
      "status": "done",
      "url": "https://yourapp.com",
      "overall_score": 7.5,
      "created_at": "2026-06-23T14:00:00Z",
      "report_url": "https://ghostuser.io/report/ab12cd34"
    },
    {
      "id": "ef56gh78",
      "status": "running",
      "url": "https://yourapp.com/pricing",
      "overall_score": null,
      "created_at": "2026-06-23T14:08:00Z",
      "report_url": "https://ghostuser.io/report/ef56gh78"
    }
  ]
}

#Personas

Each ghost is a persona — a distinct kind of user with their own goals, patience, and blind spots. Pass personas as an array of keys on POST /v1/runs to choose who tests your app. Omit it to use a sensible default set tuned for your product.

#Tiers & credits

Runs cost credits, billed on completion by actual usage. The tier trades depth for cost — higher tiers let each ghost take more steps and dig deeper, at a higher credit cost. Pick the tier that fits how thorough you need the run to be.

#Errors

Errors use standard HTTP status codes and return a consistent JSON shape with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked."
  }
}

#Rate limits

The API allows a few requests per second per key — plenty for normal use. Because runs are asynchronous, you don't hold a connection open while a test runs: you start a run, then poll GET /v1/runs/{id} on an interval.

A polling interval of every 5 seconds is a good default — runs take minutes, not milliseconds, so faster polling just burns requests. If you exceed the limit you'll get 429 rate_limited; back off and retry. Need higher limits? Reach out via the dashboard.