REST API

Every project on the account. No parameters. Use these ids with the other endpoints.

Response

{
  "projects": [
    {
      "id": "3f0a51c8-6b2e-4a7d-9c31-0b6f2a4e77d1",
      "name": "Acme Storefront",
      "createdAt": "2026-07-01T09:14:22.118Z"
    }
  ]
}

Returns 50 insights by default, sorted by score descending and then newest first - pass limit (1-100) for a different page size. When more exist than were returned, the response carries hasMore: true, so a truncated page is never mistaken for the whole list. Field meanings are documented in How insights work.

curl -s "https://betterloopai.com/api/v1/insights?projectId=$PROJECT_ID&status=new" \
  -H "Authorization: Bearer blk_your_api_key"

Response

{
  "insights": [
    {
      "id": "b41c0a8e-3d7f-4a12-9f88-2c6e5b90ad34",
      "category": "bug",
      "severity": 3,
      "title": "JS error hitting 9 sessions: Cannot read properties of undefined",
      "body": "\"Cannot read properties of undefined (reading 'total')\" fired 31 times across 9 sessions in the last 7 days (sample page: /checkout).",
      "path": "/checkout",
      "evidence": {
        "message": "Cannot read properties of undefined (reading 'total')",
        "occurrences": 31,
        "sessions": 9
      },
      "status": "new",
      "source": "rules",
      "createdAt": "2026-07-23T02:11:07.442Z"
    },
    {
      "id": "5d9e17b0-84c2-4f61-b0a7-91f3c2d84e05",
      "category": "ux",
      "severity": 2,
      "title": "Users rage-click \"Save changes\" on /settings",
      "body": "6 different sessions rapidly clicked the same element (main>form>button.btn.primary) 22 times total in the last 7 days.",
      "path": "/settings",
      "evidence": {
        "selector": "main>form>button.btn.primary",
        "clicks": 22,
        "sessions": 6,
        "windowDays": 7
      },
      "status": "new",
      "source": "rules",
      "createdAt": "2026-07-23T02:11:07.451Z"
    }
  ]
}

topPages returns up to 20 rows. webVitalsP75 has one row per metric the SDK actually captured, with the sample count behind it - a p75 over a handful of samples is not worth acting on. daily only contains days that had at least one event.

curl -s "https://betterloopai.com/api/v1/metrics?projectId=$PROJECT_ID&days=7" \
  -H "Authorization: Bearer blk_your_api_key"

Response

{
  "days": 7,
  "stats": {
    "pageviews": 18420,
    "sessions": 5231,
    "errors": 96,
    "rageClicks": 41,
    "deadClicks": 63,
    "total": 74310
  },
  "topPages": [
    { "path": "/", "views": 7210, "sessions": 3980 },
    { "path": "/pricing", "views": 3102, "sessions": 2245 }
  ],
  "webVitalsP75": [
    { "name": "LCP", "p75": 2410, "samples": 4802 },
    { "name": "INP", "p75": 184, "samples": 2911 },
    { "name": "CLS", "p75": 0.06, "samples": 3760 },
    { "name": "TTFB", "p75": 288, "samples": 5102 },
    { "name": "FCP", "p75": 1290, "samples": 4655 }
  ],
  "daily": [
    { "day": "2026-07-18", "pageviews": 2510, "sessions": 742, "errors": 11 },
    { "day": "2026-07-19", "pageviews": 2688, "sessions": 761, "errors": 9 }
  ]
}

Counting notes. sessions counts distinct session ids across all event types in the window, so it is higher than the number of sessions that produced a pageview. errors combines error and rejection events, and total is every stored event including clicks and vitals.

50 groups by default, keyed on the error message and sorted by occurrence count. Takes the same limit (1-100) and returns hasMore the same way. samplePath and sampleStack are one representative example from the group, not the only one. Unlike the insight detector, this endpoint also includes resource load failures, which appear with msg: "resource_error".

curl -s "https://betterloopai.com/api/v1/errors?projectId=$PROJECT_ID&days=30" \
  -H "Authorization: Bearer blk_your_api_key"

Response

{
  "days": 30,
  "errors": [
    {
      "msg": "Cannot read properties of undefined (reading 'total')",
      "count": 31,
      "sessions": 9,
      "lastSeen": "2026-07-24 08:12:44.201+00",
      "samplePath": "/checkout",
      "sampleStack": "TypeError: Cannot read properties of undefined (reading 'total')\n    at CartSummary (app/checkout/CartSummary.tsx:41:19)"
    },
    {
      "msg": "resource_error",
      "count": 12,
      "sessions": 7,
      "lastSeen": "2026-07-23 19:02:11.884+00",
      "samplePath": "/",
      "sampleStack": null
    }
  ]
}

lastSeen is a Postgres timestamp string with a space separator and a UTC offset, not an ISO-8601 T string. Parse it accordingly.

curl -X POST "https://betterloopai.com/api/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "bl_your_write_key",
    "sid": "manual-smoke-test",
    "url": "https://example.com",
    "vw": 1440,
    "vh": 900,
    "events": [
      { "t": "pageview", "ts": 1753344000000, "path": "/", "attrs": { "title": "Home" } }
    ]
  }'

Response

{ "ok": true }