API reference

The PagePulse REST API is available at https://api.pagepulse.dev. All requests must be authenticated with a project API key, which you can generate from your workspace settings. The API returns JSON and follows REST conventions.

Authentication

Pass your API key in the Authorization header as a Bearer token. API keys are scoped to a single project and can be revoked at any time.

curl https://api.pagepulse.dev/v2/metrics \
  -H "Authorization: Bearer pp_live_abc123"

List Web Vitals metrics

Returns Core Web Vitals for a project, optionally filtered by route, device, browser, country, and date range. The response is a JSON object with one entry per route.

GET /v2/metrics?projectId=site_123&route=/checkout&from=2025-06-01&to=2025-06-30

# Response
{
  "routes": [
    {
      "route": "/checkout",
      "samples": 42103,
      "lcp_p75": 4100,
      "inp_p75": 320,
      "cls_p75": 0.18,
      "fcp_p75": 2800,
      "ttfb_p75": 920,
      "score": 52
    }
  ]
}

Create a deployment marker

Marks a new deployment. PagePulse will begin correlating RUM samples collected after this call with the new deployment.

POST /v2/deployments
Content-Type: application/json

{
  "projectId": "site_123",
  "version": "v2.8.1",
  "environment": "production",
  "commit": "a1b2c3d"
}

Get deployment diff

Returns the before/after diff of Core Web Vitals, JavaScript bundle size, route load time, and error rate for a specific deployment.

GET /v2/deployments/dep_abc/diff?projectId=site_123

# Response
{
  "deployment": {
    "id": "dep_abc",
    "version": "v2.8.1",
    "environment": "production"
  },
  "diff": {
    "lcp_p75": { "before": 2300, "after": 1700, "delta": -600 },
    "inp_p75": { "before": 180, "after": 96, "delta": -84 },
    "jsSizeKB": { "before": 248, "after": 184, "delta": -64 }
  },
  "affectedRoutes": [...]
}

Rate limits

The API is rate-limited to 100 requests per minute per API key. If you exceed the limit, the API will respond with 429 Too Many Requests and include a Retry-After header. Rate limits reset every 60 seconds.