Ranges

Learn how to work with ranges using the Synnax TypeScript client.

In Synnax, a range is a named time interval that labels interesting events in your data. Ranges are the primary means for organizing and accessing the data stored within Synnax, and can be used to correlate metadata with channel telemetry.

Range Configuration Reference

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	Human-readable name for the range
`timeRange`	`TimeRange`	Yes	-	Time interval spanned by the range (start must be ≤ end)
`color`	string	No	-	Hex color code for identifying the range in visualizations
`key`	string	No	Auto	UUID identifier (automatically generated by Synnax if not provided)

Understanding timeRange

A TimeRange defines the start and end boundaries of a range. It specifies the time interval that the range covers.

Key Points:

Start and End: A TimeRange has two properties: start and end, both of which are timestamps
End-Exclusive: The range includes data from start up to (but not including) end
Validation: The start time must be less than or equal to the end time

Example:

import { TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/client";

// Create a TimeRange using TimeStamp and TimeSpan
const start = TimeStamp.now();
const end = start.add(TimeSpan.hours(2));
const timeRange = new TimeRange(start, end);

// Using the convenience span method (recommended)
const start = TimeStamp.now();
const timeRange = start.span(TimeSpan.hours(2));

// Create from specific date/time
const start = new TimeStamp("2023-02-12 12:30:00");
const end = new TimeStamp("2023-02-12 14:30:00");
const timeRange = new TimeRange(start, end);

Creating Ranges

To create a range, we can use the client.ranges.create method:

import { TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/client";

// Create a range with a specific time interval
const start = new TimeStamp("2023-02-12 12:30:00");
const end = new TimeStamp("2023-02-12 14:30:00");
const range = await client.ranges.create({
  name: "My Range",
  timeRange: new TimeRange(start, end),
  color: "#FF0000", // Optional: color for visualization
});

// Or use the convenience span method
const start = TimeStamp.now();
const range = await client.ranges.create({
  name: "My Range",
  timeRange: start.span(TimeSpan.hours(2)),
  color: "#FF0000",
});

This creates a range inside Synnax that you can then view from the Console.

Retrieving Ranges

We can retrieve a range using the client.ranges.retrieve method:

// you can retrieve a single range by its key or name
const tr1 = client.ranges.retrieve("9/7/2025 Hotfire");
const tr2 = client.ranges.retrieve(tr1.key);

// you can also retrieve multiple ranges by their names or keys
const trs = client.ranges.retrieve(["9/7/2025 Hotfire", "9/8/2025 Hotfire"]);
const trs2 = client.ranges.retrieve([tr1.key, tr2.key]);

// you can also retrieve by a search term
const ranges = client.ranges.retrieve({ searchTerm: "Hotfire", limit: 10 });

Synnax will throw a NotFoundError if you try to retrieve a range that does not exist, or a MultipleFoundError if you try to retrieve a range by its name and multiple ranges matching that name are found.

import { MultipleFoundError, NotFoundError } from "@synnaxlabs/client";

try {
  const tr = client.ranges.retrieve("My Range");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Range not found");
  }
  if (error instanceof MultipleFoundError) {
    console.log("Multiple ranges found");
  }
}

Retrieving Child Ranges or a Parent Range

You can also retrieve the child ranges or parent range of a range:

const tr = await client.ranges.retrieve("9/7/2025 Hotfire");
const childRanges = await tr.retrieveChildren();
const parentRange = await tr.retrieveParent();

Updating a Range

To update an existing range, we use the same client.ranges.create method but specify the key of the range we want to update. This allows us to modify the range’s name, time range, or color.

import { TimeRange, TimeStamp } from "@synnaxlabs/client";

// First, retrieve the range you want to update
const myRange = await client.ranges.retrieve("My Range");

// Update the range by providing its key and new values
const updatedRange = await client.ranges.create({
  key: myRange.key, // Specify the key to update existing range
  name: "My Updated Range", // New name
  timeRange: new TimeRange(
    new TimeStamp("2023-02-12 13:00:00"),
    new TimeStamp("2023-02-12 15:00:00"),
  ),
  color: "#00FF00", // New color
});

When updating a range, you must provide the key parameter. If you provide a key that doesn’t exist, Synnax will create a new range with that key instead of raising an error.

Updating a range will completely replace its properties. Make sure to include all the properties you want to keep, not just the ones you want to change.

Metadata

Ranges can store metadata, which is a key-value store of interesting information about the range:

const tr = await client.ranges.retrieve("9/7/2025 Hotfire");
await tr.kv.set("part_number", "12345");
const partNumber = await tr.kv.get("part_number");
console.log(partNumber); // "12345"

Deleting Ranges

You can delete a range by passing in its key to the client.ranges.delete method:

const tr = await client.ranges.retrieve("9/7/2025 Hotfire");
await client.ranges.delete(tr.key);

Channels

Read Data