Reference

API Reference

The Pulsecadence REST API allows you to export metrics, manage alert rules, and submit deploy events programmatically. All endpoints use JSON and authenticate via API key.

Authentication

Include your API key in the Authorization header on every request:

Authorization: Bearer pcd_api_YOUR_API_KEY

API keys are available in your dashboard under Settings → API Keys. Keep your API key secret — it provides read and write access to your project data.

Base URL

https://api.pulsecadence.com/v1

Endpoints

Metrics

GET /projects/{project_id}/metrics

Returns aggregated metric percentiles (p50 / p75 / p95) for the given time range and optional segment filters.

Query parameters

Parameter	Type	Description
`metric`	string	One of `lcp`, `inp`, `cls`, `ttfb`, or a custom mark name. Required.
`from`	ISO 8601	Start of time range (inclusive). Default: 24h ago.
`to`	ISO 8601	End of time range (exclusive). Default: now.
`segment`	string	Optional. Filter by segment: `device:mobile`, `connection:4g`, `country:US`.
`page_path`	string	Optional. Filter to a specific URL path (exact match or prefix with `*` wildcard).

Example response

{
  "metric": "lcp",
  "from": "2026-04-01T00:00:00Z",
  "to": "2026-04-02T00:00:00Z",
  "session_count": 4821,
  "percentiles": {
    "p50": 1840,
    "p75": 2960,
    "p95": 5420
  },
  "unit": "ms"
}

POST /projects/{project_id}/deploys

Submit a deploy event to enable deploy-correlated alerting. Pulsecadence uses this timestamp to attribute metric regressions to specific deployments.

Request body

{
  "deployed_at": "2026-04-14T14:08:00Z",
  "version": "v2.14.0",
  "deployed_by": "eng-deploy",
  "note": "Optional free-text description"
}

Response

{
  "deploy_id": "dep_m2k9x3a7",
  "status": "received"
}

Alert rules

GET /projects/{project_id}/alerts

Returns all alert rules configured for the project.

POST /projects/{project_id}/alerts

Create a new alert rule. Alert fires when the specified metric's p75 exceeds the threshold for the given segment.

Request body

{
  "name": "Checkout LCP mobile regression",
  "metric": "lcp",
  "percentile": "p75",
  "threshold_ms": 3500,
  "segment": "device:mobile",
  "page_path": "/checkout*",
  "webhook_url": "https://hooks.slack.com/services/..."
}

Rate limits

The API is rate limited to 100 requests per minute per API key. The response headers include X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns HTTP 429.

Error codes

HTTP status	Meaning
`400`	Bad request — check query parameters or request body
`401`	Invalid or missing API key
`403`	API key does not have access to this project
`404`	Project or resource not found
`429`	Rate limit exceeded
`500`	Internal error — retry with exponential backoff