# Deep links and URL parameters

A deep link opens Explore directly into a specific query, time range, dataset, view, or visualization. The URL is human-readable: every parameter is plain text, so you can read, hand-edit, and build links by setting parameters like `?query=…&dataset=…&duration=…`.

Use a deep link when you want to send a teammate the exact view you are looking at, embed a link in a runbook or alert webhook, or generate links programmatically.

## What you need

To open a URL built with query parameters, you must be signed in to a Coralogix account on the same domain as the URL. If you do not have access to the dataset or saved view referenced in the URL, the link returns a permission error.

## URL parameters

All parameters are optional. Omitted parameters fall back to the defaults listed in the following tables.

### Core parameters

| Parameter   | Description                                                                                                                                    | Example               |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `query`     | Search expression. In DataPrime mode, the full DataPrime query. In Lucene mode, the Lucene filter text.                                        | `status:500`          |
| `queryType` | Query language. Default: `lucene`.                                                                                                             | `dataprime`, `lucene` |
| `dataset`   | Data source. Default: `logs`. Accepts `logs`, `spans`, or a custom dataset as `<dataspace>/<name>`.                                            | `spans`               |
| `duration`  | Relative time range as a slug. Default: `last-1-hour`. Takes precedence over `from` and `to`. See [Relative time slugs](#relative-time-slugs). | `last-15-minutes`     |
| `from`      | Absolute window start, Unix timestamp in milliseconds. Used only when `duration` is unset.                                                     | `1718960400000`       |
| `to`        | Absolute window end, Unix timestamp in milliseconds. Used only when `duration` is unset.                                                       | `1718964000000`       |
| `viewId`    | Load a saved view by ID.                                                                                                                       | —                     |

### Query shaping (Lucene mode)

| Parameter   | Description                                                                                                             | Example        |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- | -------------- |
| `groupBy`   | Group-by chips. Comma-joined `[key:]value` per chip.                                                                    | `service.name` |
| `aggregate` | Aggregate chips. Comma-joined `key:value` per chip, where `key` is the function and `value` is the field or expression. | `count:*`      |

### Spans-only parameters

These apply when `dataset=spans`.

| Parameter        | Description                                                                                                              | Example                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `spansError`     | Errors-only flag.                                                                                                        | `true`                                                                           |
| `spansDuration`  | Duration filter. `p<decimal>` for a percentile, or `<minUs>-<maxUs>` microsecond bounds (an empty side means unbounded). | `p0.95`, `100000-`, `0-5000000`                                                  |
| `spansRelations` | Relation filters. `~`-joined rows of `<type>:<operator>:<field>:<v1>,<v2>`.                                              | —                                                                                |
| `spansView`      | Spans view mode. Default: `spans`.                                                                                       | `spans`, `traces`, `analyze`, `overview`, `highlights`, `red-metrics`, `latency` |

### Display and grid

| Parameter | Description                                                                             | Example                                                                                   |
| --------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `sort`    | Sort order. Comma-joined `field:dir` pairs.                                             | `timestamp:desc`                                                                          |
| `limit`   | Result limit.                                                                           | `100`                                                                                     |
| `page`    | Active tab type. Default: `logs`.                                                       | `logs`, `templates`, `traces`, `overview`                                                 |
| `viz`     | Visualization type. The grid (table) is the omitted default.                            | `table`, `line`, `line-area`, `bar-horizontal`, `bar-vertical`, `pie`, `scatter`, `mixed` |
| `rows`    | Grid row style. Default: `1-line`.                                                      | `1-line`, `2-lines`, `json`, `condensed`, `list`                                          |
| `cols`    | Selected grid columns. Ordered, comma-joined field paths. Column widths aren't encoded. | `timestamp,severity,service.name`                                                         |

### Relative time slugs

The `duration` parameter accepts these slugs. Slugs are stable and independent of UI translations, so external links don't break when on-screen captions change.

`last-1-minute`, `last-2-minutes`, `last-5-minutes`, `last-15-minutes`, `last-30-minutes`, `last-1-hour`, `last-2-hours`, `last-6-hours`, `last-12-hours`, `last-24-hours`, `today`, `last-2-days`, `last-3-days`, `last-5-days`, `last-7-days`.

`today` resolves to the start of the current day through now. Every other slug is a rolling window relative to "now" at page load.

### Build the URL

```javascript
https://<team>.<domain>/#/explore?<parameters>
```

Replace `<team>` with your Coralogix team subdomain and `<domain>` with your region (for example, `eu2.coralogix.com`).

## Build a URL with URL Builder

If you would rather not type parameters by hand, use **URL Builder** from the Explore actions menu in the top-right corner of the Explore screen.

URL Builder opens a form where you select the parameters from a list, set their values, and copy the resulting URL.

Use URL Builder when you want to:

- Compose a URL without remembering the parameter names or syntax.
- Add or remove parameters quickly to experiment with different combinations before settling on the final URL.
- Validate that the parameters you set produce a working URL before sharing.
- Generate URLs from a runbook template or alert webhook payload without manually URL-encoding values.

The URL that URL Builder generates is identical to one you would write by hand using the parameters in the table above. After copying, paste it into your runbook, ticket, dashboard tooltip, or webhook payload.

### URL Builder versus Copy URL

The Explore actions menu also has a **Copy URL** option. The two are for different jobs:

- Use **Copy URL** to share the exact view you are looking at right now. The URL captures the current query, filters, time range, and saved view.
- Use **URL Builder** to compose a URL from scratch with parameters you choose, including parameters not currently active in your view.

## Backward compatibility

Older Explore URLs continue to work. Explore accepts the legacy inputs in the following table, normalizes them to the canonical parameters when the page loads, and rewrites the address bar to the canonical form. Existing bookmarks, runbook links, dashboard tooltips, and alert webhook payloads keep working without changes.

| Legacy input                    | Canonical equivalent                                |
| ------------------------------- | --------------------------------------------------- |
| Path `/#/explore/logs`          | Path `/#/explore`                                   |
| `relativeTime=<slug>`           | `duration=<slug>`                                   |
| `preset=today`                  | `duration=today`                                    |
| `appendFilter=<expression>`     | Merged into `query` as an `AND` clause              |
| `dataId=…&uiId=…` (opaque blob) | Decoded once and replaced with canonical parameters |

When you build new links, use the canonical parameters in [URL parameters](#url-parameters).

## Pick a URL pattern

Two primary patterns cover most use cases.

### Static query URL

Construct a query entirely through URL parameters. Best for runbooks, scripts, alert webhooks, and integrations where you want predictable, repeatable behavior.

Generic syntax:

```javascript
https://<team>.<domain>/#/explore?query=<query>&duration=<slug>
```

For example, open today's error logs:

```javascript
https://acme.coralogix.com/#/explore?query=severity:error&duration=today
```

For example, open the same query in DataPrime syntax against the spans dataset, last hour, table visualization:

```javascript
https://acme.coralogix.com/#/explore?queryType=dataprime&query=source%20spans%20|%20filter%20status_code%20==%20%22ERROR%22&dataset=spans&duration=last-1-hour&viz=table
```

### Saved view with filter overlay

Load a saved view as a base, then narrow it with a filter using `appendFilter`. Best when teams maintain a shared saved view (such as an APM errors view) and individuals need to focus on a specific service or host.

Generic syntax:

```javascript
https://<team>.<domain>/#/explore?viewId=<saved_view_id>&appendFilter=<key>:<value>
```

For example, narrow a saved view of APM errors (`viewId=123`) to a specific service:

```javascript
https://acme.coralogix.com/#/explore?viewId=123&appendFilter=coralogix.metadata.subsystemName:ws-service-catalog
```

When the page loads, Explore resolves the saved view and `appendFilter`, then rewrites the URL to canonical parameters — the address bar shows the resolved `query` instead of `viewId` and `appendFilter`.

## Examples by product

### Real User Monitoring

Find error events in a specific environment. Opens Explore with the last 15 minutes of RUM error events (`cx_rum.event_context.severity:5`) from a specific environment.

Generic syntax:

```javascript
https://<team>.<domain>/#/explore?duration=last-15-minutes&query=cx_rum.event_context.severity:5 AND cx_rum.environment:<environment>
```

For example:

```javascript
https://acme.coralogix.com/#/explore?duration=last-15-minutes&query=cx_rum.event_context.severity:5 AND cx_rum.environment:cx498
```

Open all session activity for a specific session. Filters logs to a single RUM session over the last 15 minutes.

```javascript
https://acme.coralogix.com/#/explore?duration=last-15-minutes&query=cx_rum.session_context.session_id:"00760ea8-1562-40fc-964e-b4213c2e2b72"
```

### APM

Filter logs to a specific service. Filters today's logs by `subsystemName`, the Coralogix metadata field representing a service.

```javascript
https://acme.coralogix.com/#/explore?duration=today&query=coralogix.metadata.subsystemName:"ws-service-catalog"
```

### Infrastructure

Open Kubernetes cluster errors. Filters logs to errors in a specific cluster.

```javascript
https://acme.coralogix.com/#/explore?query=resource.attributes.k8s_cluster_name:"cx498" AND severity:"ERROR"
```

### Traces

Open spans for a specific trace. Filters the spans dataset to a single trace, grouped by service:

```javascript
https://acme.coralogix.com/#/explore?dataset=spans&query=trace_id:"40f7fcf2945d459a94a7a599a3935bf3"&groupBy=service.name
```

## Encode special characters in the URL

When a query contains spaces, quotes, or other special characters, the browser encodes those characters automatically when the URL loads. For example, the query:

```javascript
severity:"ERROR" AND host:"prod"
```

May appear in the address bar as:

```javascript
query=severity:"ERROR"%3aAND%3ahost:"prod"
```

This is expected. The browser converts reserved characters into a percent-encoded form so the URL stays valid, and Coralogix decodes the value on the receiving end. You do not need to do anything.

If you are constructing a URL programmatically, use your language's standard URL-encoding function:

- JavaScript: `encodeURIComponent`
- Python: `urllib.parse.quote`
- Go: `url.QueryEscape`

## Best practices

A few patterns help you build URLs that work the first time and stay useful over time.

### Pick the right time parameter

Pick a relative range or an absolute window:

- `duration` for a relative range. Use a slug like `last-15-minutes`, `last-1-hour`, or `today`. The range resolves against "now" every time the link opens, so it always shows the freshest matching window. Best for runbooks, monitoring, and ongoing investigations.
- `from` and `to` for an absolute window as Unix timestamps in milliseconds. The link always shows the same time range regardless of when someone opens it. Best for incident postmortems, audit trails, and any link that needs to be reproducible.

`duration` takes precedence over `from` and `to`. Use one approach per link.

### Use viewId for stable views and appendFilter for one-offs

If your team maintains a public saved view that everyone uses (for example, a "production errors" view), share its `viewId` rather than rebuilding the same query in every URL. When you need to add a one-off filter on top of that saved view, use `appendFilter` instead of duplicating the saved view.

### URL-encode when constructing programmatically

When you build URLs in a script or runbook generator, use your language's URL-encoding function so spaces, quotes, and other special characters are handled consistently.

### Confirm permissions before sharing

The recipient must be signed in to a Coralogix account on the same domain and must have access to the dataset and saved view referenced in the URL. If you share with users outside your team, confirm their access first.

### Test the link before sharing

Open the URL in a private window or another browser profile to confirm it loads the expected query, time range, and filters. Catching a typo before sharing saves a round of "the link does not work" follow-ups.

## Use it in your workflows

Explore query parameters reduce friction in any workflow that takes someone to a filtered view of their data. Common places to use them:

- **Runbooks in PagerDuty, Opsgenie, or Incident.io.** Replace "open Coralogix and search for X" with a one-click link that opens Coralogix already filtered to the affected service and time window.
- **Slack and Microsoft Teams alert notifications.** Add a "View logs" button to alert webhook payloads so responders open Explore with the alert's labels and evaluation window pre-applied.
- **Status pages and customer-facing transparency.** Link from an internal status page to a saved view that shows live error rates for a specific service.
- **Cross-team handoffs in Jira and GitHub.** Paste a URL into a ticket or pull request so the recipient lands on the same view you are looking at, without describing how to reproduce the search.
- **CI and CD pipeline failure reports.** Have a failing build script post a deep link to the logs from that deploy window.
- **Custom Dashboards drilldowns.** Embed URLs in dashboard tooltips so a chart can drill down to its underlying logs.
- **Customer support escalations.** Share a pre-filtered link from a support ticket to engineering instead of attaching screenshots.
- **Internal wikis in Notion or Confluence.** Embed live, pre-filtered links to Coralogix queries instead of static screenshots that go stale.
- **Automation scripts and integrations.** Construct links programmatically in any workflow that takes a user to specific telemetry.

## Troubleshoot

| Problem                                    | Cause                                                                                                               | Resolution                                                                                                                                       |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Permission error on link open              | The recipient does not have access to the dataset or saved view in the URL.                                         | Grant the recipient access, or share a screenshot or export instead.                                                                             |
| Link opens an empty Explore screen         | The query syntax is invalid for the `queryType`, or the dataset has no matches in the time range.                   | Verify the query parses in the chosen syntax. Widen the time range or remove filters to confirm data exists.                                     |
| Time range looks wrong                     | The link mixes `duration` with `from`/`to`, or uses a legacy alias (`relativeTime`, `preset`) alongside `duration`. | Keep one time parameter per URL. When `duration` is set, omit `from` and `to`.                                                                   |
| Saved view loads but the filter is missing | `appendFilter` is set without `viewId`.                                                                             | Add a `viewId` to the URL when using `appendFilter`, or write the filter directly into `query`.                                                  |
| Spans parameters have no effect            | `dataset` isn't set to `spans`.                                                                                     | Add `dataset=spans` to the URL. The `spansError`, `spansDuration`, `spansRelations`, and `spansView` parameters apply only to the spans dataset. |

## Learn more

- [Lucene query reference](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html)
- [DataPrime reference guide](https://coralogix.com/docs/dataprime/introduction/welcome-to-the-dataprime-reference/index.md)
- [Explore actions](https://coralogix.com/docs/user-guides/data_exploration/explore_actions/index.md)
- [Export data](https://coralogix.com/docs/user-guides/data_exploration/export/index.md)

## Next steps

Share the exact view you are looking at right now with the Copy URL action in [Explore actions](https://coralogix.com/docs/user-guides/data_exploration/explore_actions/index.md).