Quickstart

From an API key to a published capture, a browser session, an analytical job and an MCP client.

1. Create an API key

Sign in at /run/app, open API keys and create one. The panel shows the key once; copy it straight into your shell or secret store:

export BROWSERGRID_API_KEY='bgk_...'

Check Credit on the same page. Work is admitted against your available credit, so top up first if it is zero. See Credit and billing.

2. Capture a page

Submit a batch. This one renders a single page with render-fetch, which needs the exact hosts the page may load from:

curl -s https://grid-lab.zyxio.xyz/batches \
  -H "x-api-key: $BROWSERGRID_API_KEY" \
  -H "content-type: application/json" \
  -d '{"urls": ["https://example.com/"], "script": "render-fetch", "params": {"allowedHosts": ["example.com"]}}'

{"batchId": "6f1d2c3e-8a4b-4e5f-9a0b-1c2d3e4f5a6b", "jobCount": 1}

Poll the batch until completed + failed equals total. Workers start on demand, so the first results of a quiet grid can take a minute or two.

curl -s https://grid-lab.zyxio.xyz/batches/6f1d2c3e-8a4b-4e5f-9a0b-1c2d3e4f5a6b \
  -H "x-api-key: $BROWSERGRID_API_KEY"

Each entry of jobs has a jobId. Ask for a download URL of the rendered HTML and fetch it within 15 minutes:

curl -s https://grid-lab.zyxio.xyz/artifacts/<jobId>/html -H "x-api-key: $BROWSERGRID_API_KEY"
curl -s -o page.html '<the url from the answer>'

This item costs €0.0008 when it is published. If it fails, it costs nothing.

3. Lease a browser

curl -s https://grid-lab.zyxio.xyz/sessions \
  -H "x-api-key: $BROWSERGRID_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ttlMinutes": 10}'

Keep the cdpUrl from the answer: it is shown only here. Poll GET /sessions until your sessionId is running with an attestation, then connect:

import { chromium } from 'playwright'
const browser = await chromium.connectOverCDP(process.env.CDP_URL)

Release it when you are done, on every exit path:

curl -s -X DELETE https://grid-lab.zyxio.xyz/sessions/<sessionId> -H "x-api-key: $BROWSERGRID_API_KEY"

You pay €0.07 per hour from the moment the browser is ready until you release it; start-up is free.

4. Run an analytical job

Jobs run container images from repositories admitted on the grid's registry; ask us to admit yours. Replace the image below with your own:

curl -s https://grid-lab.zyxio.xyz/jobs \
  -H "x-api-key: $BROWSERGRID_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "image": "registry.grid.zyxio.xyz/<your-repository>:<tag>",
    "command": ["python", "-c", "print(6 * 7)"],
    "resources": {
      "cpu": {"request": "1", "limit": "1"},
      "memory": {"request": "1Gi", "limit": "1Gi"},
      "ephemeralStorage": {"request": "256Mi", "limit": "1Gi"}
    },
    "runningDeadlineSeconds": 600,
    "capabilities": {"networkProfile": "none"},
    "env": {}, "labels": {}, "idempotencyKey": "quickstart-1"
  }'

Poll GET /jobs/<jobId> until phase is SUCCEEDED, FAILED, TIMED_OUT or CANCELLED, then read the output with GET /jobs/<jobId>/logs. This job reserves 7,733 µ€, about €0.0077 (1 vCPU and 1 GiB for 600 seconds), and is charged only for the time it actually ran.

5. Connect an MCP client

With a key, register the endpoint with its header. For Claude Code:

claude mcp add --transport http browsergrid https://grid-lab.zyxio.xyz/mcp \
  --header "x-api-key: $BROWSERGRID_API_KEY"

Or sign in with Zyxio instead of a key: register the URL alone and follow the client's sign-in prompt. See MCP.