---
title: nexyron.entity_time_range
url: https://nexyron.tech/docs/cypher/procedures/temporal-and-streaming/nexyron-entity-time-range
description: Scan timeline events for a selected list of subject node IDs over a time range.
---

# nexyron.entity_time_range

## Generic Description

Scan timeline events for a selected list of subject node IDs over a time range.

Simple example:

```cypher
CALL nexyron.entity_time_range([0, 1], 0, 60000, 'Reading')
YIELD node_id, source_id, kind, tag, start_ts, end_ts, weight
RETURN node_id, source_id, kind, tag, start_ts, end_ts, weight
ORDER BY start_ts
```

The `from_ts` and `to_ts` bounds are canonical `i64` epoch-millisecond integers. `currenttimestamp()`, `now()`, `timestamp()`, `date(...)`, and `datetime(...)` return that format, and plus/minus integer arithmetic uses milliseconds.

## Consumer-Level Explanation

Use `nexyron.entity_time_range` when you already know which entities matter and want a bounded temporal scan for just those subjects. Use these procedures when cataloged temporal storage is the source of truth rather than an ad hoc list assembled inside one Cypher expression.

## Conceptual Explanation

This is the targeted counterpart to `nexyron.global_time_range`. It keeps the same event-style output shape but narrows the scan to one selected entity set, which makes it more appropriate for user history, asset history, or case-specific investigations.

## More Detailed Explanation

In practical queries, start by deciding the row grain you want after the call: one row per node, one row per path, one row per registry object, one row per artifact, or one row per summary. Then keep that grain explicit with `YIELD` and named projections. That is the difference between a useful planner-facing example and a vague call that downstream tooling cannot safely compose. For contract-driven procedures, the executable examples on these pages intentionally inspect procedure metadata unless the required named artifacts are created in the same example.

## Advanced Example

```cypher
CALL nexyron.entity_time_range([0, 1], currenttimestamp() - 604800000, currenttimestamp(), null)
YIELD node_id, source_id, kind, tag, start_ts, end_ts, weight
RETURN node_id, source_id, kind, tag, start_ts, end_ts, weight
ORDER BY node_id, start_ts DESC
LIMIT 20
```

## Real Use Cases

-   per-device telemetry playback
-   incident timelines for a selected service set
-   user or account history reconstruction
-   compose the procedure output with `YIELD`, `WITH`, and `RETURN` rather than hiding follow-up logic outside Cypher

## Real Limitations And Tradeoffs

-   you must already know the subject node IDs
-   large subject lists can still be expensive
-   procedure calls are explicit contracts; missing state, unsupported parameters, or absent artifacts should fail rather than silently falling back