Skip to main content

RUM API

The RUM API lets you load aggregated RUM metrics or export individual page views.

Loading RUM metrics​

Use the getRumMetrics(projectId) method to load RUM data for a given project.

const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  filters: {
    device: "mobile",
  },
});
console.log(rumData);

The endpoint returns aggregate RUM metrics. The value shows the metric value (by default the 75th percentile) and the count shows the number of page views included.

{
  "info": {
    "groupBy": "urlPath",
    "stat": "p75",
    "from": "2024-04-25T20:15:00.000Z",
    "to": "2024-05-26T20:15:00.000Z"
  },
  "lcp": [
    {
      "count": 115,
      "urlPath": "/",
      "value": 1614
    },
    {
      "count": 70,
      "urlPath": "/product",
      "value": 698
    },
    "..."
  ],
  "cls": ["..."],
  "inp": ["..."],
  "fcp": ["..."],
  "ttfb": ["..."]
}

Use the from and to parameters to specify a date range. Pass in custom metrics with the metrics parameter. Use device or urlPath filters to only include specific experiences.

const MS_PER_DAY = 24 * 60 * 60 * 1000;
const rumData = await debugbear.projects.getRumMetrics("123", {
  from: new Date(new Date().valueOf() - 31 * MS_PER_DAY),
  to: new Date(),
  metrics: ["load", "dcl", "fcp"],
  filters: {
    urlPath: ["/"],
  },
});

Available metrics, filtering options, and grouping options​

You can find the full list of RUM metrics here and the full list of properties for filtering and grouping here.

Stat parameter​

By default, the API reports the 75th percentile for metric values. However, you can also pass in avg, sum, p50, p90, or p95.

const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  stat: "p90",
});

Filtering by metric value​

You can use metrics in filters by passing in an object with from and/or to values.

const rumData = await debugbear.projects.getRumMetrics(project.id, {
  groupBy: "navigationType",
  filters: {
    fcp: { to: 2000 },
  },
});

Using cURL​

curl https://www.debugbear.com/api/v1/project/12345/rumMetrics  \
  -X GET \
  -G \
  -d from=2020-02-01T00:00:00Z \
  -d to=2025-08-01T00:00:00Z \
  -d fcp=-2000 \
  -H "x-api-key: API_KEY"

Providing a filter type​

You can also use negative filters (isNot) and wildcard matches (matches) or doesNotMatch for wildcard exclusion.

The available filter types are:

  • is (default): Include only exact matches
  • isNot: Exclude exact matches
  • matches: Include wildcard pattern matches using * as a wildcard character (can use multiple wildcards in a single pattern, e.g., /project/*/rum/*/overview)
  • doesNotMatch: Exclude wildcard pattern matches
// Wildcard match
const rumData = await debugbear.projects.getRumMetrics(project.id, {
  filters: {
    urlPath: { value: "/blog/changelog-*", type: "matches" },
  },
});

// Negative filter (exclude)
const rumData = await debugbear.projects.getRumMetrics(project.id, {
  filters: {
    urlPath: { value: ["/admin", "/internal"], type: "isNot" },
  },
});

Filter type restrictions​

  • is and isNot: Available on all filters (both breakdown properties and metrics)
  • matches and doesNotMatch: Only available on breakdown properties (text fields like urlPath, country, device, etc.) as listed here.

Ordering and limiting results​

You can control the order and number of categories returned when using groupBy:

maxCategories​

Limits the number of categories returned. If there are more categories than this limit, only the top categories will be returned based on the ordering parameters.

The default value is 20, but you can increase it up to 500.

const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  maxCategories: 10, // Return only top 10 URLs
});

orderBy​

Controls whether to order results by the number of experiences (count) or by the metric value (value). Default is count.

// Order by number of page views (default)
const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  orderBy: "count",
});

// Order by metric value (e.g., LCP milliseconds)
const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  orderBy: "value",
});

orderByDirection​

Sets the sort direction. Default is desc (descending).

// Get URLs with the slowest LCP values first
const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  orderBy: "value",
  orderByDirection: "desc", // Slowest first
});

// Get URLs with the fastest LCP values first
const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  orderBy: "value",
  orderByDirection: "asc", // Fastest first
});

Combining ordering parameters​

// Get the 5 URLs with the most page views
const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  maxCategories: 5,
  orderBy: "count",
  orderByDirection: "desc",
});

// Get the 10 slowest URLs by LCP
const rumData = await debugbear.projects.getRumMetrics("123", {
  groupBy: "urlPath",
  maxCategories: 10,
  orderBy: "value",
  orderByDirection: "desc",
});

Complete filter examples​

Here are comprehensive examples showing different ways to filter RUM data:

// Filter by single URL path
const rumData = await debugbear.projects.getRumMetrics("123", {
  filters: { urlPath: "/product/123" },
});

// Filter by multiple URL paths
const rumData = await debugbear.projects.getRumMetrics("123", {
  filters: { urlPath: ["/product/123", "/product/456"] },
});

// Exclude specific paths
const rumData = await debugbear.projects.getRumMetrics("123", {
  filters: {
    urlPath: {
      value: ["/admin", "/internal"],
      type: "isNot",
    },
  },
});

// Wildcard pattern matching (supports multiple wildcards)
const rumData = await debugbear.projects.getRumMetrics("123", {
  filters: {
    urlPath: {
      value: "/project/*/rum/*/overview", // Matches /project/123/rum/54/overview
      type: "matches",
    },
  },
});

// Combine multiple filters
const rumData = await debugbear.projects.getRumMetrics("123", {
  filters: {
    urlPath: {
      value: "/checkout/*",
      type: "matches",
    },
    device: "mobile",
    lcp: { from: 2500 }, // LCP > 2.5 seconds
  },
});

Loading individual RUM page views​

Use getRumPageViews(projectId) to load the most recent RUM page views for a project, instead of the aggregated metrics returned by getRumMetrics. The endpoint returns up to 5000 page views ordered by date descending.

const pageViews = await debugbear.projects.getRumPageViews("123");
console.log(pageViews[0]);

Each page view is a flat object containing the metric values, URL, country, device, navigation type, and other properties that were recorded.

{
  "domain": "www.debugbear.com",
  "ttfbValue": 2308,
  "fcp": 4108,
  "lcpValue": 5317,
  "lcpSelector": "#__docusaurus_skipToContent_fallback img.img_CujE",
  "lcpText": "Histogram",
  "lcpUrl": "https://www.debugbear.com/dimg/d7303b86df4121c764b45dfdf88835b1.png",
  "clsScrollTop": null,
  "inpValue": null,
  "inpStartTime": null,
  "inpSelector": null,
  "inpText": null,
  "inpEventName": null,
  "date": "2026-04-14T20:30:15.000Z",
  "country": "CA",
  "operatingSystem": "Mac OS",
  "pageTitle": "Working With Percentiles: What Do p50, p75, And p90 Mean? | DebugBear",
  "origin": "https://www.debugbear.com",
  "device": "desktop",
  "path": "/docs/rum/percentiles",
  "queryString": "",
  "devicePixelRatio": 2,
  "windowHeight": 940,
  "windowWidth": 1650
}
tip

Fields that aren't available for a given page view (for example, no CLS or INP occurred) are returned as null:

Filtering page views​

The same filter options as getRumMetrics are available. Use count to cap the number of rows returned (up to a maximum of 5000).

const MS_PER_DAY = 24 * 60 * 60 * 1000;
const pageViews = await debugbear.projects.getRumPageViews("123", {
  from: new Date(Date.now() - 7 * MS_PER_DAY),
  to: new Date(),
  count: 200,
  filters: {
    device: "mobile",
    urlPath: { value: "/checkout/*", type: "matches" },
    lcp: { from: 2500 },
  },
});

Using cURL​

curl https://www.debugbear.com/api/v1/project/12345/rumPageViews \
  -X GET \
  -G \
  -d from=2025-05-01T00:00:00Z \
  -d to=2025-05-18T00:00:00Z \
  -d device=mobile \
  -d count=500 \
  -H "x-api-key: API_KEY"
Last updated on