---
url: 'https://docs.codatum.com/features/notebook/parameter/url.md'
description: Specifying parameter values through URL query parameters
---

# Specifying values from a URL

When creating an external link, you can override a parameter's value by adding it to the URL.

## Applicable features

The following features let you specify parameters from a URL. With these features, the URL updates each time you change a parameter, so sharing the URL also shares the parameter values.

* Notebook [versions](../version)
* [Reports](../sharing/report/overview)
  * Applies to **interactive reports**.
  * If **Auto-run** is enabled, the report runs automatically after merging in the URL-specified parameters.
  * Even if **Use parameter default values** is enabled, **parameters specified in the URL take priority** (they're reset to default first, and then the URL-specified values are applied).

## How to specify

Parameters are synced with the `cdm.params` query parameter in the URL. The format is as follows.

```typescript
// Keyed by page ID so values are retained across page navigation
type Params = { [pageId: string]: { [paramId: string]: string } };

// Each value is a JSON.stringify'd string
// pageId / paramId are actually IDs like 68783eb9c4b4b71483a1d617
const params: Params = {
  page1: {
    param1: JSON.stringify('value1'),
    param2: JSON.stringify(123),
  },
  page2: {
    param3: JSON.stringify(true),
    param4: JSON.stringify(['value1', 'value2']),
  },
};

const query = `?cdm.params=${encodeURIComponent(JSON.stringify(params))}`;
```

## Shortcut format

If `cdm.params` is hard to construct directly, you can also use the `cdm.params.${paramId}` format. If both are present, `cdm.params.${paramId}` takes priority, and the merged result is reflected as a new `cdm.params` in the URL.

```typescript
const paramId = 'param1';
// JSON.stringify isn't needed for the shortcut format (but encodeURIComponent is)
const value = 'string_value';

const query = `?cdm.params.${paramId}=${encodeURIComponent(value)}`;

// Specifying an empty string clears that parameter
const queryEmpty = `?cdm.params.${paramId}=`;
```

## How to specify values

How to specify values differs by parameter type. `JSON.stringify` isn't needed for the shortcut format, but `encodeURIComponent` is still needed when placing the value in the URL.

| Type | Specifying via `cdm.params` | Shortcut format |
| --- | --- | --- |
| Text input / Text select | `JSON.stringify("string_value")` | `string_value` |
| Text multi input / Text multi select | `JSON.stringify(["item1", "item2"])` | `item1,item2` |
| Number input / Number select | `JSON.stringify(123)` | `123` |
| Date input | `JSON.stringify("2025-01-01")` | `2025-01-01` |
| Date range | `JSON.stringify(["2025-01-01", "2025-01-02"])` | `2025-01-01,2025-01-02` |
| Checkbox | `JSON.stringify(true)` or `JSON.stringify(false)` | `true` or `false` |

* For array types, use `,` as the separator in the shortcut format.
* Date input and date range use `YYYY-MM-DD` format.
* An invalid value results in an error screen.