> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-rum.md).

# Query RUM and Upload Source Maps

Search RUM sessions and events, query time series, retrieve replay data, and upload source maps.

Use the RUM API to analyze browser and mobile sessions and events, retrieve recorded replays, and upload source maps for error symbolication.

### Endpoints

| Operation                     | Endpoint                                        |
| ----------------------------- | ----------------------------------------------- |
| Search events with gcQL       | **POST** `/api/rum/records/search`              |
| Search sessions with gcQL     | **POST** `/api/rum/sessions/search`             |
| Event time series             | **POST** `/api/rum/records/search-time-series`  |
| Session time series           | **POST** `/api/rum/sessions/search-time-series` |
| List web or mobile sessions   | **POST** `/api/rum/sessions/query`              |
| Retrieve session details      | **POST** `/api/rum/session/details`             |
| Retrieve replay events        | **POST** `/api/rum/session/replay`              |
| Replay event counts over time | **POST** `/api/rum/session/replay/velocity`     |
| Upload a source map           | **POST** `/api/rum/sourcemaps`                  |

The event-search URL uses `records`, not `events`.

### Authentication

Send an [API key](https://docs.groundcover.com/administer/api-keys.md) in `Authorization: Bearer <YOUR_API_KEY>` and select the backend with `X-Backend-Id: <YOUR_BACKEND_ID>`. Self-hosted deployments use their own API base URL.

### gcQL Request Body

| Field            | Type   | Description                                                        |
| ---------------- | ------ | ------------------------------------------------------------------ |
| `start`, `end`   | string | Time range in RFC3339 format.                                      |
| `query`          | string | Required gcQL query. Raw `pipeline` objects are not accepted.      |
| `sources`        | array  | Optional structured scope conditions, also applied to joined data. |
| `filters`        | string | Optional additional filters.                                       |
| `bucketDuration` | string | Required for time series, for example `1m` or `5m`.                |
| `valueField`     | string | Numeric result alias to chart.                                     |
| `fillValue`      | number | Optional replacement for empty time buckets; defaults to `null`.   |

### Example: Sessions with Errors

```bash
curl --request POST 'https://api.groundcover.com/api/rum/sessions/search' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-28T10:00:00Z",
    "end": "2026-10-28T11:00:00Z",
    "query": "error_type:TypeError | fields session_id | limit 20"
  }'
```

Session searches can reference event-only fields such as `error_type`; the API automatically joins the event data. Event searches can similarly reference session-only fields. To query events, change the URL to `/api/rum/records/search`.

The response wraps result rows in `data` and lists numeric fields in `valueFieldHints`:

```json
{
  "data": [{"session_id": "example-session"}],
  "valueFieldHints": []
}
```

The session identifier above is illustrative. Session search finds sessions active in the requested window; `_time` in a session query refers to session start time. By default, the search looks back up to four hours before the window for sessions that started earlier. Such sessions can still appear if active during the window.

### Example: RUM Events over Time

```bash
curl --request POST 'https://api.groundcover.com/api/rum/records/search-time-series' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-28T10:00:00Z",
    "end": "2026-10-28T11:00:00Z",
    "query": "* | stats count() as total",
    "bucketDuration": "1m",
    "valueField": "total",
    "fillValue": 0
  }'
```

The response is an array of series with `metric` labels and `velocity` points. An aggregation is required; the API adds the time bucket. Change the URL to `/api/rum/sessions/search-time-series` to aggregate sessions. See [Time-Series Queries](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/time-series-queries.md).

### List Web or Mobile Sessions

For the session-list format used by the RUM page, use `/api/rum/sessions/query`:

```bash
curl --request POST 'https://api.groundcover.com/api/rum/sessions/query' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-28T10:00:00Z",
    "end": "2026-10-28T11:00:00Z",
    "sortBy": "startTime",
    "sortOrder": "desc",
    "limit": 20,
    "skip": 0,
    "category": "rum"
  }'
```

`start`, `end`, `sortBy`, `sortOrder`, and `limit` are required. `skip` defaults to zero. Set `category` to `mobile-rum` for mobile sessions from the React Native, Flutter, iOS, and Android SDKs; omitted category defaults to `rum` (browser). Mobile sessions also return `osName`, `osVersion`, `deviceModel`, `deviceBrand`, and `appVersion`. `sortOrder` is `asc` or `desc`. Supported sort fields are `sessionID`, `startTime`, `endTime`, `userEmail`, `userId`, `country`, `isMobile`, `browser`, `sessionErrors`, `pageCount`, `durationMilli`, `osName`, and `deviceModel`.

The response contains `sessions`, with identifiers in `sessionID`. This differs from the gcQL field name `session_id`.

### Retrieve Session Details or Replay

```bash
curl --request POST 'https://api.groundcover.com/api/rum/session/replay' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-28T10:00:00Z",
    "end": "2026-10-28T11:00:00Z",
    "sessionID": "<SESSION_ID>"
  }'
```

All three fields are required. The response contains an `events` array; each entry has `timestamp`, `eventID`, and a string `data` containing the replay payload. The session must have replay data collected.

Use the same request with `/api/rum/session/details` to retrieve `events` and `metrics` such as LCP, CLS, INP, and page-load time. Details also accepts optional `category` (`rum` or `mobile-rum`). For replay event counts, POST to `/api/rum/session/replay/velocity` and add `"bucketDuration": "1m"`; the response contains `series`.

### Upload a Source Map

```bash
curl --request POST 'https://api.groundcover.com/api/rum/sourcemaps' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --form 'app_id=checkout-web' \
  --form 'release_id=example-release' \
  --form 'file=@dist/app.js.map'
```

All three multipart fields are required. `app_id` and `release_id` accept letters, numbers, dots, hyphens and underscores. Use the identifiers emitted by your application. Let cURL set the multipart `Content-Type` boundary. The upload limit is configurable, with a default of 100 MiB.

Success returns HTTP `201` with `status`, `app_id`, `release_id`, `filename`, and `size_bytes`.

### Errors

Malformed requests, invalid gcQL, or time-series queries without aggregation return HTTP `400`. A backend without the gcQL RUM endpoints returns `404`. Source-map uploads can fail with `502` or `503` if the upload service is unavailable; upload size limits also apply.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-rum.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
