API & CLI Paid

Trigger audits programmatically from your CI/CD pipeline, scripts, or the command line. This is the best way to integrate xcelera into your deployment workflow.

For the full endpoint specification, see the API Reference. To ask questions about the same data in an LLM client, see the MCP server.

When to use the API

CI/CD pipelines — audit on every deploy or pull request
Custom scheduling — trigger audits at specific times using your own scheduler (cron, GitHub Actions schedules, etc.)
Automation — integrate xcelera into your monitoring or deployment tooling

Creating an API token

Go to Settings → API Tokens
Click Generate Token
Copy the token immediately — it cannot be retrieved later

You can have up to 5 active tokens per organization. Tokens can be deactivated from the same settings page.

A read-only token can call every GET endpoint but can't start audits or register pages. CI needs a full-access token.

Store your API token securely. Never commit tokens to your repository or share them in plain text. Use environment variables or your CI provider's secret management.

Triggering an audit

Send a POST request to /api/v1/audits with your page ref:

curl -X POST https://xcelera.dev/api/v1/audits \
  -H "Authorization: Bearer $XCELERA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref": "homepage"}'

The response comes back as soon as the audit is scheduled. Poll it by id, and watch status until it is Succeeded or Failed:

curl -H "Authorization: Bearer $XCELERA_TOKEN" \
  https://xcelera.dev/api/v1/audits/ah7n75i5uxk6fce9wanzeq8d

For the full request schema including auth and git context options, see the API Reference.

Adding Git context

Pass git information to link audits to commits and enable GitHub check runs:

curl -X POST https://xcelera.dev/api/v1/audits \
  -H "Authorization: Bearer $XCELERA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "homepage",
    "context": {
      "git": {
        "owner": "my-org",
        "repo": "my-repo",
        "branch": "main",
        "commit": {
          "hash": "abc1234",
          "message": "Deploy v2.1",
          "date": "2025-01-15T10:30:00Z"
        }
      }
    }
  }'

With git context in place you can look an audit back up by commit or PR instead of by id:

curl -H "Authorization: Bearer $XCELERA_TOKEN" \
  "https://xcelera.dev/api/v1/audits?ref=homepage&gitHash=abc1234"
 
curl -H "Authorization: Bearer $XCELERA_TOKEN" \
  "https://xcelera.dev/api/v1/audits/compare?ref=homepage&prNumber=42"

GitHub Actions example

- name: Run xcelera Audit
  run: |
    curl -X POST https://xcelera.dev/api/v1/audits \
      -H "Authorization: Bearer ${{ secrets.XCELERA_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{
        "ref": "homepage",
        "context": {
          "service": "GitHub Actions",
          "buildNumber": "${{ github.run_number }}",
          "buildUrl": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}",
          "prNumber": ${{ github.event.pull_request.number || 0 }},
          "git": {
            "owner": "${{ github.repository_owner }}",
            "repo": "${{ github.event.repository.name }}",
            "branch": "${{ github.head_ref }}",
            "commit": {
              "hash": "${{ github.event.pull_request.head.sha }}",
              "message": "${{ github.event.pull_request.title }}",
              "date": "${{ github.event.pull_request.updated_at }}"
            }
          }
        }
      }'

Add XCELERA_TOKEN as a GitHub Actions secret in your repository settings. With git context included, you'll get GitHub check runs on your PRs automatically.

CLI

The CLI wraps the same API, and detects git context from your local repository so you don't pass branch and commit by hand.

Commands are xcelera <noun> <verb>. Run xcelera help for the full list, or xcelera help <noun> <verb> for the options of one command.

Command	Does
`xcelera page list`	Lists tracked pages and their latest scores — find refs
`xcelera page create`	Registers a page and prints its ref
`xcelera page archive`	Archives a page
`xcelera audit run`	Starts an audit (`xcelera audit` is shorthand)
`xcelera audit get`	Fetches an existing audit

Authentication

Every command takes --token, or reads XCELERA_TOKEN from the environment. XCELERA_API_URL overrides the base URL (default https://xcelera.dev).

export XCELERA_TOKEN=xc_...

Registering a page

xcelera page create --url https://example.com --name Homepage
xcelera page create --url https://example.com --device desktop

Registration is an upsert — the same url and device returns the page that already exists, so a deploy script can call it every run. The page starts with no schedule; audit it with xcelera audit run.

Running an audit

xcelera audit run --ref homepage-x4f2
xcelera audit run --ref homepage-x4f2 --wait --timeout 900

Without --wait the command exits as soon as the audit is scheduled. With --wait it polls until the audit finishes and prints the scores.

For pages behind a login, pass credentials the audit should use — see Auditing secure pages:

xcelera audit run --ref homepage-x4f2 --cookie "session=abc123"
xcelera audit run --ref homepage-x4f2 --header "Authorization: Bearer eyJhbG..."
xcelera audit run --ref homepage-x4f2 --cookie-file ./cookies.txt

Fetching an audit

audit get reads an existing audit without starting anything. A bare --ref gives the page's latest succeeded audit.

xcelera audit get --ref homepage-x4f2
xcelera audit get --ref homepage-x4f2 --pr 42
xcelera audit get --audit-id ah7n75i5uxk6fce9wanzeq8d

Machine-readable output

Every command takes --json, which prints the raw API response instead of the human report — pipe it into jq in a script. page list also takes --csv.

xcelera page list --json | jq -r '.pages[] | "\(.ref) \(.scores.performance.raw)"'
xcelera page list --csv > pages.csv

Exit codes

Code	Meaning
`0`	The command succeeded
`1`	Usage error, API error, or — with `--wait` — the audit failed or timed out

The CLI uses the same API under the hood. Anything you can do with the CLI can also be done with direct API calls.