# How to Get a Point-in-Time Snapshot of the Semantica Graph: 4 Methods Explained

> Easily get a point-in-time snapshot of your Semantica graph using the API endpoint or CLI skill. Learn 4 methods for temporal data retrieval.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Retrieve a point-in-time snapshot of the Semantica graph by calling the `GET /api/temporal/snapshot` endpoint with an optional `at` ISO-8601 timestamp parameter, or use the built-in CLI skill `semantica:temporal snapshot`.**

The semantica-agi/semantica repository implements a **bi-temporal knowledge graph** that maintains complete historical state, allowing you to query the graph as it existed at any previous moment. This guide demonstrates how to extract a point-in-time snapshot of the Semantica graph using the platform's HTTP API, frontend components, and command-line tools.

## Understanding the Temporal Snapshot Endpoint

Semantica exposes a dedicated HTTP endpoint for retrieving historical graph states. The `GET /api/temporal/snapshot` endpoint accepts an optional `at` query parameter containing an ISO-8601 timestamp. When omitted, the endpoint returns the current state. When provided, it reconstructs the graph exactly as it existed at that specific moment.

According to the API documentation in [`docs/reference/explorer.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/explorer.md), the endpoint returns a JSON payload containing the complete set of nodes, edges, and metadata for the requested temporal state. The test suite in [`tests/explorer/test_explorer_api.py`](https://github.com/semantica-agi/semantica/blob/main/tests/explorer/test_explorer_api.py) (lines 518-531) validates this behavior across multiple historic timestamps.

## Method 1: Querying via HTTP API with cURL

The fastest way to test the snapshot functionality is through a direct HTTP request. This approach requires no client libraries and works with standard command-line tools.

```bash
curl -X GET "http://localhost:8000/api/temporal/snapshot?at=2025-06-15T00:00:00"

```

The response contains the full graph structure as it existed at the specified timestamp, including all node properties and edge relationships that were valid at that point.

## Method 2: Frontend JavaScript Implementation

The Explorer UI fetches snapshots directly when users navigate to historical positions. The implementation in [`explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx) (lines 1540-1545) demonstrates the standard fetch pattern used by the frontend.

```javascript
async function fetchSnapshot(atIso) {
  const url = `/api/temporal/snapshot?at=${encodeURIComponent(atIso)}`;
  const response = await fetch(url);
  if (!response.ok) throw new Error('Snapshot request failed');
  const snapshot = await response.json();
  return snapshot;   // { nodes: [...], edges: [...], ... }
}

// Example usage
fetchSnapshot('2025-06-15T00:00:00')
  .then(snap => console.log('Graph snapshot:', snap));

```

This pattern handles URL encoding automatically and parses the JSON response into a usable graph object containing nodes and edges arrays.

## Method 3: Python Client Script

For programmatic access within Python applications, use the `requests` library to interact with the snapshot endpoint. This approach is ideal for data analysis pipelines or backup scripts.

```python
import requests

def get_snapshot(at: str | None = None):
    params = {'at': at} if at else {}
    resp = requests.get(
        'http://localhost:8000/api/temporal/snapshot', 
        params=params
    )
    resp.raise_for_status()
    return resp.json()

# Example: fetch the graph as of 15 June 2025

snapshot = get_snapshot('2025-06-15T00:00:00')
print(snapshot)

```

The function defaults to the current time when no timestamp is provided, matching the endpoint's native behavior.

## Method 4: CLI Skill Invocation

Semantica ships with a built-in **temporal skill** that wraps the HTTP API for command-line usage. As documented in [`plugins/skills/temporal/SKILL.md`](https://github.com/semantica-agi/semantica/blob/main/plugins/skills/temporal/SKILL.md), this skill provides convenient syntax for snapshot retrieval.

```bash

# Obtain a point-in-time snapshot and pretty-print it

semantica:temporal snapshot --at 2025-06-15T00:00:00 | jq .

```

This method handles authentication and endpoint configuration automatically, using the local Semantica instance's default settings.

## Key Implementation Files

The following source files define and test the snapshot functionality:

- **[`explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx`](https://github.com/semantica-agi/semantica/blob/main/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx)** (lines 1540-1545): Contains the React component logic that requests snapshots when users navigate to temporal positions in the Explorer interface.

- **[`tests/explorer/test_explorer_api.py`](https://github.com/semantica-agi/semantica/blob/main/tests/explorer/test_explorer_api.py)** (lines 518-531): Houses integration tests verifying that the snapshot endpoint correctly reconstructs historical graph states from various timestamps.

- **[`docs/reference/explorer.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/explorer.md)**: Provides the official API reference documentation for the `GET /api/temporal/snapshot` endpoint and its parameter specifications.

- **[`plugins/skills/temporal/SKILL.md`](https://github.com/semantica-agi/semantica/blob/main/plugins/skills/temporal/SKILL.md)**: Defines the CLI skill interface, documenting command syntax and usage examples for the `semantica:temporal snapshot` command.

## Summary

- The `GET /api/temporal/snapshot` endpoint returns complete graph states for any valid ISO-8601 timestamp provided via the `at` query parameter.
- The GraphWorkspace component in [`GraphWorkspace.tsx`](https://github.com/semantica-agi/semantica/blob/main/GraphWorkspace.tsx) implements the standard frontend pattern for fetching snapshots during temporal navigation.
- Python clients can retrieve snapshots using standard HTTP libraries, with optional timestamp parameters defaulting to the current time.
- The Semantica CLI provides a wrapped `semantica:temporal snapshot` command for command-line automation and scripting.
- Integration tests in [`test_explorer_api.py`](https://github.com/semantica-agi/semantica/blob/main/test_explorer_api.py) confirm that historical state reconstruction functions correctly across the bi-temporal data model.

## Frequently Asked Questions

### What timestamp format does the Semantica snapshot endpoint require?

The endpoint accepts any valid **ISO-8601 timestamp** (e.g., `2025-06-15T00:00:00`). The system parses this string according to standard datetime conventions and retrieves the graph state valid at that exact moment.

### How do I retrieve the current state without specifying a timestamp?

Omit the `at` parameter entirely. According to the API documentation in [`docs/reference/explorer.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/explorer.md), the endpoint defaults to the current system time when no timestamp is provided, returning the most recent graph state.

### Which source file handles snapshot requests in the Explorer frontend?

The [`GraphWorkspace.tsx`](https://github.com/semantica-agi/semantica/blob/main/GraphWorkspace.tsx) file located at `explorer/src/workspaces/GraphWorkspace/` contains the fetch logic at lines 1540-1545. This component calls `/api/temporal/snapshot` whenever users interact with the temporal navigation controls.

### Can I automate snapshot retrieval using the Semantica CLI?

Yes. The `semantica:temporal snapshot` command documented in [`plugins/skills/temporal/SKILL.md`](https://github.com/semantica-agi/semantica/blob/main/plugins/skills/temporal/SKILL.md) enables scripted snapshot extraction. Combine this with tools like `jq` or redirection operators to process or store the JSON output in automated workflows.