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.

Grouping by time​

By default the API returns one aggregate value for the whole date range. Use groupByTime to split the results into time buckets instead. The supported values are hour, day, and week.

const rumData = await debugbear.projects.getRumMetrics("123", {
from: new Date("2026-04-06T00:00:00Z"),
to: new Date("2026-04-08T00:00:00Z"),
metrics: ["lcp"],
groupByTime: "day",
});

Each result gains a date field with the start of the bucket, and the count and value apply to that bucket rather than to the whole range. Results are ordered oldest first, and buckets without page views are left out.

{
"info": {
"groupBy": null,
"groupByTime": "day",
"stat": "p75",
"from": "2026-04-06T00:00:00.000Z",
"to": "2026-04-08T00:00:00.000Z"
},
"lcp": [
{ "date": "2026-04-06T00:00:00.000Z", "count": 2, "value": 1400 },
{ "date": "2026-04-07T00:00:00.000Z", "count": 1, "value": 2000 }
]
}

Add groupBy to get a separate series for each category:

// Daily LCP for each device type
const rumData = await debugbear.projects.getRumMetrics("123", {
from: new Date("2026-04-01T00:00:00Z"),
to: new Date("2026-05-01T00:00:00Z"),
groupBy: "device",
groupByTime: "day",
});

Using cURL​

curl https://www.debugbear.com/api/v1/project/12345/rumMetrics \
-X GET \
-G \
-d from=2026-04-06T00:00:00Z \
-d to=2026-04-08T00:00:00Z \
-d metrics=lcp \
-d groupByTime=day \
-H "x-api-key: API_KEY"

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.

Filtering and grouping by query parameters​

Any URL query parameter that gets collected can be used for filtering and grouping, using queryParam.<name> as the property ID. A page view of /pricing?variant=b has a queryParam.variant value of b.

// Compare LCP between the variants of an A/B test
const rumData = await debugbear.projects.getRumMetrics("123", {
groupBy: "queryParam.variant",
metrics: ["lcp"],
});

// Only include page views that came from one campaign
const rumData = await debugbear.projects.getRumMetrics("123", {
filters: {
"queryParam.utm_source": "newsletter",
},
});

Results are keyed by the full property ID, and page views that didn't have the parameter are grouped under null.

{
"info": {
"groupBy": "queryParam.variant",
"stat": "p75",
"from": "2026-04-01T00:00:00.000Z",
"to": "2026-05-01T00:00:00.000Z"
},
"lcp": [
{ "count": 420, "queryParam.variant": "a", "value": 1610 },
{ "count": 395, "queryParam.variant": "b", "value": 2240 },
{ "count": 180, "queryParam.variant": null, "value": 1700 }
]
}

Query parameters behave like any other property, so all four filter types work, and the null and notNull values filter on whether the parameter was there at all.

// Page views whose URL had no variant parameter
filters: { "queryParam.variant": "null" }

// Page views that had the parameter, whatever its value
filters: { "queryParam.variant": "notNull" }

// Exclude one value
filters: { "queryParam.variant": { value: "b", type: "isNot" } }

// Match several values
filters: { "queryParam.variant": ["a", "b"] }

Using cURL​

curl https://www.debugbear.com/api/v1/project/12345/rumMetrics \
-X GET \
-G \
-d groupBy=queryParam.variant \
-d metrics=lcp \
-d queryParam.utm_source=newsletter \
-H "x-api-key: API_KEY"

To filter on several values of the same parameter, repeat the field with a [] suffix:

curl https://www.debugbear.com/api/v1/project/12345/rumMetrics \
-X GET \
-G \
-d "queryParam.variant[]=a" \
-d "queryParam.variant[]=b" \
-H "x-api-key: API_KEY"

Parameters that appear more than once​

A URL can repeat a parameter, as in /search?tag=shoes&tag=red. That page view has both values, so grouping by queryParam.tag counts it once under shoes and once under red. The group counts can therefore add up to more than the total number of page views. Repeating the same value, as in ?tag=red&tag=red, is only counted once.

Repeated parameters are often written with a [] suffix, as in /search?tag[]=shoes&tag[]=red. The suffix is not part of the name, so those values are also grouped under queryParam.tag.

A parameter with no value, like the debug in /pricing?debug, is reported as an empty string rather than as null.

Parameters that are not collected​

Filtering by a parameter that was never stored returns no page views, so it is worth knowing which ones are left out:

  • Parameters that commonly carry personal data or tracking identifiers, including password, token, code, state, gclid, fbclid and twclid, along with any name containing token. Values that look like an email address are dropped as well.
  • Parameter names ending in _type, because that suffix is how the API takes a filter type.
  • Names longer than 64 characters, or containing anything other than letters, numbers, _, . and -.
  • Everything, if query parameter collection is turned off for the project. See RUM data privacy.

Very long query strings are cut off, and the parameter that got cut is dropped rather than stored with a partial value.

utm_campaign is a special case. It has a UTM Campaign property of its own, and queryParam.utm_campaign reads from that, so the two IDs return the same data.

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.

maxCategories only limits categories. It doesn't limit how many time buckets groupByTime returns, so a daily breakdown over three months returns every day.

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"

Managing RUM page groups​

Page groups decide which bucket a page view is reported under. You can list, create, update and delete them through the API, which is useful when your site's URL structure is generated and you want the groups to follow it.

tip

A page group only applies to page views recorded after it is set up. Changing a group does not move page views that have already been collected.

Listing page groups​

Page views are matched against the groups in order, and the first group that matches wins, so the order the list comes back in is the order that matters.

const pageGroups = await debugbear.rumPageGroups.list("123");
console.log(pageGroups);
[
{
"id": "456",
"name": "Excluded Pages",
"type": "url",
"paths": ["/admin/*"],
"urlRegExps": [],
"cssSelector": null,
"sampling": 0,
"order": 0
},
{
"id": "457",
"name": "Product Pages",
"type": "url",
"paths": ["/product/*"],
"urlRegExps": [],
"cssSelector": null,
"sampling": null,
"order": 1
}
]

Creating a page group​

name is required. Everything else is optional, and a group with nothing to match on simply matches no page views, so you can create one and fill it in later.

const pageGroup = await debugbear.rumPageGroups.create("123", {
name: "Checkout",
type: "url",
paths: ["/checkout", "/cart/*"],
});

Without an order the new group goes last, so it only picks up page views that none of your existing groups already match.

Page view matching options​

type decides which field is used to match a page view:

typeMatched against
urlpaths, a list of URL paths that may contain * wildcards
urlRegExpurlRegExps, regular expressions matched against the full URL
selectorcssSelector, a selector looked for on the page

A regular expression is matched against the host name, path and query string together, so remember to allow for the parts you are not interested in:

await debugbear.rumPageGroups.create("123", {
name: "Promo campaign",
type: "urlRegExp",
urlRegExps: ["^.*/product\\?utm_campaign=promo.*$"],
});

Regular expressions are checked when you save them. A pattern that does not compile is rejected with a 400 rather than accepted and then quietly matching nothing.

Excluding pages from data collection​

Set sampling to 0 to stop collecting the page views a group matches. Those views are not reported to DebugBear and do not count against your page view quota. Leave sampling as null to collect at your project's usual rate.

await debugbear.rumPageGroups.create("123", {
name: "Admin pages",
type: "url",
paths: ["/admin/*"],
sampling: 0,
});

Updating a page group​

Only the fields you pass are changed.

await debugbear.rumPageGroups.update("457", {
paths: ["/product/*", "/products/*"],
});

Deleting a page group​

await debugbear.rumPageGroups.delete("457");

Page views that used to match the deleted group are reported under whichever group matches them next, or under no group. Page views already collected keep the group they were recorded with.

Using cURL​

curl https://www.debugbear.com/api/v1/project/12345/rumPageGroups \
-H "x-api-key: API_KEY"
curl https://www.debugbear.com/api/v1/project/12345/rumPageGroups \
-X POST \
-H "x-api-key: API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Checkout","type":"url","paths":["/checkout"]}'
curl https://www.debugbear.com/api/v1/rumPageGroups/457 \
-X PATCH \
-H "x-api-key: API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Checkout pages"}'
curl https://www.debugbear.com/api/v1/rumPageGroups/457 \
-X DELETE \
-H "x-api-key: API_KEY"