Pulspeed Documentation

Performance monitoring API for developers and AI agents. One API call returns Core Web Vitals, AI analysis, and improvement recommendations.

Quick Start 30 seconds to first scan

1. Get your API token from Settings → API Tokens.

2. Run your first scan:

curl -X POST https://pulspeed.ai/api/v2/scan \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

3. Response (synchronous — ~30s):

{
  "data": {
    "id": 42,
    "performance_score": 84,
    "metrics": {
      "fcp": 1240, "lcp": 2450, "tti": 3100,
      "tbt": 180,  "ttfb": 420, "cls": 0.04
    },
    "analysis": "Your LCP of 2.45s is above the 2.5s threshold...",
    "strategy": "mobile",
    "taken_at": "2026-02-22T10:00:00Z"
  },
  "meta": { "message": "Scan completed", "site_id": 7 }
}

Authentication

All API endpoints (except /register and /login) require a Bearer token:

Authorization: Bearer <your_api_token>

Tokens are created in Settings → API Tokens. Tokens never expire unless manually revoked.

Base URLs

All responses include an X-API-Version header with the served version.

Response Format

All responses are JSON. Successful responses wrap data in a data key. Collection responses include pagination metadata.

// Single resource
{ "data": { "id": 1, ... } }

// Collection
{ "data": [ {...}, {...} ] }

// With metadata
{
  "data": { ... },
  "meta": { "request_id": "req_abc", "message": "..." }
}

Every response includes these headers:

Error Codes

All errors follow a consistent structure:

{
  "error": {
    "code": "scan_limit_exceeded",
    "message": "Monthly scan limit of 30 reached for your free plan.",
    "request_id": "req_01abc123",
    "docs_url": "https://pulspeed.ai/docs#errors"
  }
}

Rate Limits

When rate limited, you receive 429 Too Many Requests with a Retry-After header.

Plans & Limits

Scan a URL and get results in one call. Auto-creates the site if it doesn't exist. By default blocks until the scan completes (~30–60s).

Request body

{
  "data": {
    "id": 42,
    "performance_score": 84,
    "metrics": {
      "fcp": 1240, "lcp": 2450,
      "tti": 3100, "tbt": 180,
      "ttfb": 420, "cls": 0.04
    },
    "analysis": "...",
    "strategy": "mobile",
    "taken_at": "2026-02-22T10:00:00Z"
  }
}

{
  "data": {
    "id": 99,
    "site_id": 7,
    "status": "pending",
    "source": "api_v2"
  },
  "meta": {
    "message": "Scan job dispatched"
  }
}

Poll async job status via GET /api/v2/scan-jobs/{id}.

Dispatch scans for up to 10 URLs at once. All jobs are queued immediately. Poll the batch endpoint to track overall progress.

POST request body

{
  "data": {
    "batch_id": "550e8400-...",
    "status": "pending",
    "total": 3,
    "jobs": [
      {"url":"https://example.com","job_id":10,"status":"queued"},
      {"url":"https://example.com/about","job_id":11,"status":"queued"},
      {"url":"https://example.com/blog","job_id":12,"status":"queued"}
    ]
  },
  "meta": { "poll_url": "/api/v2/scan/bulk/550e8400-..." }
}

{
  "data": {
    "batch_id": "550e8400-...",
    "status": "done",
    "strategy": "mobile",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "pending": 0,
    "jobs": [
      {"job_id":10,"url":"https://example.com",
       "status":"done","finished_at":"..."},
      ...
    ]
  }
}

Batch statuses: pending → processing → done | partially_done

Returns Core Web Vitals, trend analysis, and historical data over a specified period.

{
  "data": {
    "url": "https://example.com",
    "site_id": 7,
    "current": { "performance_score": 84, "fcp": 1240, "lcp": 2450, ... },
    "trend": "improving",
    "history": [ { "performance_score": 80, "taken_at": "..." }, ... ],
    "period": "7d"
  }
}

Trend values: improving | stable | declining | insufficient_data

Returns current billing-period consumption, quota, and plan limits.

{
  "data": {
    "plan": "developer",
    "period": { "start": "2026-02-01", "end": "2026-02-28" },
    "scans":       { "used": 42, "limit": 500, "remaining": 458 },
    "ai_analyses": { "used": 15, "limit": 500, "remaining": 485 }
  }
}

Push events to your endpoint after scans complete or performance thresholds are breached. Requires Developer or Scale plan.

Create endpoint

POST /api/v2/webhooks
{
  "url": "https://myapp.com/hooks/pulspeed",
  "events": ["scan.completed", "performance.regression"],
  "config": {
    "regression_delta": 5,   // trigger if score drops ≥5 pts
    "threshold_score": 70    // trigger if score < 70
  }
}

Available events:

Payload structure

{
  "id": "evt_550e8400-e29b-...",
  "event": "scan.completed",
  "created_at": "2026-02-22T10:00:00Z",
  "data": {
    "site_id": 7,
    "site_url": "https://example.com",
    "scan_job_id": 42,
    "snapshot": { "performance_score": 84, "fcp": 1240, ... }
  }
}

Verifying signatures

Every delivery includes X-Pulspeed-Signature: sha256=<hmac>. Verify it to reject spoofed requests:

# Python
import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Node.js
const crypto = require('crypto');
function verify(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

Deliveries are retried 3 times on failure: after 60s, 5 min, 30 min.

Define acceptable thresholds. When a scan violates a budget, the threshold.exceeded webhook fires.

PUT /api/v2/sites/7/budgets
{
  "performance_score": { "min": 80 },
  "lcp":  { "max": 2500 },
  "tbt":  { "max": 200 },
  "cls":  { "max": 0.1 }
}

Returns the full Lighthouse audit object for a specific audit key. Useful for debugging detailed resource issues.

GET /api/v2/snapshots/42/raw-audit/render-blocking-resources

# Response
{
  "data": {
    "snapshot_id": 42,
    "audit_key": "render-blocking-resources",
    "audit": {
      "title": "Eliminate render-blocking resources",
      "score": 0.4,
      "displayValue": "Potential savings of 540 ms",
      "details": {
        "items": [
          { "url": "https://example.com/style.css", "wastedMs": 320 }
        ]
      }
    }
  }
}

Common audit keys: render-blocking-resources, bootup-time, unused-javascript, uses-optimized-images, network-requests.

Trigger scans from GitHub Actions or other CI systems using a webhook token (separate from your API token). Requires Scale plan.

POST /api/v1/webhook/scan
Authorization: Bearer <webhook_token>
{
  "repository": { "full_name": "myorg/myrepo" }
}

MCP Server

The @pulspeed/mcp-server exposes Pulspeed as a Model Context Protocol (MCP) tool, letting AI agents — Claude, Cursor, Windsurf — directly trigger scans, read metrics, and get recommendations.

Installation

Claude Code (CLI)

claude mcp add pulspeed -- npx -y @pulspeed/mcp-server

# Set your API key
export PULSPEED_API_KEY="your_token_here"

Claude Desktop / Cursor / Windsurf

Add to your MCP config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pulspeed": {
      "command": "npx",
      "args": ["-y", "@pulspeed/mcp-server"],
      "env": { "PULSPEED_API_KEY": "your_token_here" }
    }
  }
}

Custom API endpoint

"env": {
  "PULSPEED_API_KEY": "your_token",
  "PULSPEED_BASE_URL": "https://pulspeed.ai/api/v1"
}

Tools Reference

10 tools available. All tools accept url or site_id to identify a site.

// Params
{ "url": "https://example.com", "strategy": "mobile", "wait": true }
// strategy: "mobile" | "desktop" (default: mobile)
// wait: true = block until done (default), false = async + job_id

{ "urls": ["https://example.com", "https://example.com/about"],
  "strategy": "mobile",
  "wait": false }  // false (default) = async, true = sequential+results

// No parameters required

{ "url": "https://example.com", "period": "7d" }
// period: "24h" | "7d" | "30d" | "90d" (default: 7d)

{ "url": "https://example.com" }

{ "url": "https://example.com" }  // compares latest two
// or specify: { "snapshot_id_a": 42, "snapshot_id_b": 38 }

{ "url": "https://example.com",
  "threshold": 3,   // min score drop to count (default: 3)
  "limit": 20 }     // scan history to analyse (default: 20)

// No parameters required

{ "url": "https://example.com",
  "performance_score": { "min": 80 },
  "lcp": { "max": 2500 },
  "cls": { "max": 0.1 } }

{ "url": "https://example.com",
  "audit_key": "render-blocking-resources" }
// Common keys: render-blocking-resources, bootup-time,
// unused-javascript, uses-optimized-images, network-requests

User: "My site score dropped today. What happened?"

Claude:
  → list_regressions(url="https://mysite.com", threshold=5)
     "🔴 CRITICAL −12 pts: 78 → 66 on 2026-02-22"
  → compare_snapshots(url="https://mysite.com")
     "LCP regressed: 2100ms → 3800ms (+81%)"
  → get_raw_audit(url="https://mysite.com", audit_key="bootup-time")
     "analytics.js: 1840ms — saves 1.2s if deferred"

Claude: "Your LCP jumped 1.7s due to a new analytics script
blocking the main thread for 1.84s. Defer or async-load it."