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 matchesisNot: Exclude exact matchesmatches: 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
isandisNot: Available on all filters (both breakdown properties and metrics)matchesanddoesNotMatch: Only available on breakdown properties (text fields likeurlPath,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,fbclidandtwclid, along with any name containingtoken. 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
}
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.
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:
type | Matched against |
|---|---|
url | paths, a list of URL paths that may contain * wildcards |
urlRegExp | urlRegExps, regular expressions matched against the full URL |
selector | cssSelector, 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"