Docs
→
Getting Started
→
Quick Start

Getting Started

First-run workflow for the current HeadlessX dashboard and API

by saifyxpro

This guide assumes the stack is already running locally or in Docker.

1. Open the dashboard

Go to http://localhost:3000.

The dashboard is the fastest way to create the initial runtime objects you need:

  • API keys
  • profiles
  • proxies
  • runtime settings

2. Create an API key

Open Settings → API Keys and create a key. You will use that key for curl, scripts, and automation tools.

The dashboard now proxies its own API calls server-side. External tools should still call the backend directly with X-API-Key.

3. Create a profile (optional but useful)

Profiles are useful when you want persistent sessions, cookies, or a reusable browser context.

Via dashboard

Go to Profiles and create a profile with local storage or a saved proxy.

Via API

4. Run your first scrape

Fast HTML without JS rendering

JS-rendered HTML

Use this for sites that populate content after page load.

Markdown extraction

5. Watch a streaming job

The website stream endpoint is useful when you want progress updates or a reconnectable job ID.

You will receive events such as start, progress, result, and done.

6. Use the playground

The dashboard playground is useful for checking request behavior before wiring an integration.

Website playground

  • Supports HTML, JS-rendered HTML, content extraction, screenshots, and streaming
  • Uses the same backend routes documented in API Reference

Google SERP playground

  • Uses the Google SERP endpoints
  • Supports normal result mode and streamed progress/results

Visual debugging

If you need to inspect what the browser is doing, set browserHeadless to false in the dashboard settings or update config through /api/config.

Good first checks when a target misbehaves

  1. Test html before html-js
  2. Add a waitForSelector that represents real content, not just body
  3. Use a profile if the site relies on persistent state
  4. Expect explicit challenge errors on protected sites rather than silent success

Next steps