> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Historical Infrastructure State with Time Machine

> Use Tolmo's temporal graph attributes firstSeenAt and lastSeenAt to query when infrastructure resources appeared, changed, or went stale.

Every node and edge in the Tolmo infrastructure graph carries two temporal attributes — `firstSeenAt` and `lastSeenAt` — stored as epoch milliseconds. These let you query the historical state of your infrastructure: what resources appeared recently, which ones have gone stale, and how relationships have changed over time. You can combine these queries with `--json` output and standard Unix tools to build lightweight change-detection workflows directly from the CLI.

## Temporal Attributes

The Tolmo graph crawler stamps every resource and relationship it discovers with two timestamps:

| Attribute     | Type     | Description                                               |
| ------------- | -------- | --------------------------------------------------------- |
| `firstSeenAt` | epoch ms | When the resource was first discovered by a crawler       |
| `lastSeenAt`  | epoch ms | When the resource was most recently observed by a crawler |

Both attributes are available on:

* **`GraphNode`** nodes — representing individual infrastructure resources such as EC2 instances, IAM roles, S3 buckets, and more.
* **`GRAPH_EDGE`** relationships — representing the connections between resources, such as an IAM role attached to a Lambda function.

## Example Queries

Use `tolmo cypher` to run Cypher queries directly against the infrastructure graph. The examples below demonstrate the most common time machine patterns.

**Resources added in the last 7 days:**

```bash theme={null}
tolmo cypher "MATCH (n:GraphNode) WHERE n.firstSeenAt >= (timestamp() - 7*24*60*60*1000) RETURN n.resourceType, n.resourceKey ORDER BY n.firstSeenAt DESC"
```

**Stale resources not seen in 48 hours:**

```bash theme={null}
tolmo cypher "MATCH (n:GraphNode) WHERE n.lastSeenAt < (timestamp() - 48*60*60*1000) RETURN n.resourceType, n.resourceKey LIMIT 50"
```

**New relationships established in the last 24 hours:**

```bash theme={null}
tolmo cypher "MATCH ()-[r:GRAPH_EDGE]->() WHERE r.firstSeenAt >= (timestamp() - 24*60*60*1000) RETURN r.type, count(r) AS cnt ORDER BY cnt DESC"
```

## Get JSON Output for Scripting

Add `--json` to any `tolmo cypher` command to receive machine-readable output instead of a formatted table. This is useful when you want to feed results into a script, a CI step, or a downstream tool:

```bash theme={null}
tolmo cypher --json "MATCH (n:GraphNode) WHERE n.firstSeenAt >= (timestamp() - 7*24*60*60*1000) RETURN n.resourceType, n.resourceKey ORDER BY n.firstSeenAt DESC"
```

<Tip>
  Combine time machine queries with `--json` and pipe the output to `jq` for fast, in-terminal filtering of large result sets. For example: `tolmo cypher --json "..." | jq '.[] | select(.resourceType == "aws_s3_bucket")'`
</Tip>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Detect new infrastructure">
    Query `firstSeenAt` to catch resources that appeared after a deployment or infrastructure change event. Set the time window to match your deployment cadence — for example, resources created in the last hour — to surface anything that was provisioned unexpectedly or outside of your normal release process. This is especially useful after running Terraform, CDK, or other IaC tools to verify that only the expected resources were created.
  </Accordion>

  <Accordion title="Find stale or decommissioned resources">
    Use `lastSeenAt` to identify resources the crawler has not seen recently. A resource with a `lastSeenAt` far in the past suggests it may have been deleted, shut down, or become unreachable since it was last observed. Filter by resource type — for example, EC2 instances or ECS services — to narrow down decommissioned compute before acting on it.
  </Accordion>

  <Accordion title="Audit relationship changes">
    Query `GRAPH_EDGE` `firstSeenAt` to see when connections between resources were first established. For example, you can find when an IAM role gained access to an S3 bucket, or when a Lambda function was linked to a VPC. This gives you a lightweight audit trail of permission and connectivity changes without requiring a dedicated change-log system.
  </Accordion>
</AccordionGroup>