---
title: "Analysis & Graph API"
description: "Advanced analysis endpoints for impact analysis, cycle detection, and graph queries"
keywords: [analysis, impact analysis, cycles, graph, shortest path, dependencies]
---

# Analysis & Graph API

The Analysis API provides advanced capabilities for analyzing traceability relationships, detecting cycles, finding paths, and querying the dependency graph.

## Impact Analysis

Analyze the impact of changing or deleting an item by finding all items that depend on it.

### Endpoint

```
GET /api/v1/analysis/impact/{item_id}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `item_id` | string | Yes | Item ID to analyze |

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID |

### Request Example

```bash
curl -X GET "https://api.tracertm.dev/v1/analysis/impact/item_req_001?project_id=proj_123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### Response

```json
{
  "root_item_id": "item_req_001",
  "total_affected": 15,
  "max_depth": 3,
  "affected_items": [
    {
      "id": "item_test_001",
      "title": "Test Case 1",
      "depth": 1,
      "link_type": "verified_by"
    },
    {
      "id": "item_design_001",
      "title": "Design Document 1",
      "depth": 2,
      "link_type": "implements"
    }
  ]
}
```

### Python Example

```python
from tracertm import TraceRTM

client = TraceRTM(api_key="rtm_live_abc123...")

# Analyze impact
impact = client.analysis.impact(
    item_id="item_req_001",
    project_id="proj_123"
)

print(f"Total affected items: {impact.total_affected}")
print(f"Max depth: {impact.max_depth}")

for item in impact.affected_items:
    print(f"  - {item.title} (depth: {item.depth})")
```

## Cycle Detection

Detect circular dependencies in the project's traceability graph.

### Endpoint

```
GET /api/v1/analysis/cycles/{project_id}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID to analyze |

### Request Example

```bash
curl -X GET "https://api.tracertm.dev/v1/analysis/cycles/proj_123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### Response

```json
{
  "has_cycles": true,
  "total_cycles": 2,
  "severity": "medium",
  "affected_items": [
    "item_req_001",
    "item_req_002",
    "item_req_003"
  ]
}
```

### Python Example

```python
# Detect cycles
cycles = client.analysis.detect_cycles(project_id="proj_123")

if cycles.has_cycles:
    print(f"Warning: {cycles.total_cycles} cycles detected")
    print(f"Severity: {cycles.severity}")
    print(f"Affected items: {cycles.affected_items}")
else:
    print("No cycles detected")
```

## Shortest Path

Find the shortest path between two items in the traceability graph.

### Endpoint

```
GET /api/v1/analysis/shortest-path
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID |
| `source_id` | string | Yes | Source item ID |
| `target_id` | string | Yes | Target item ID |

### Request Example

```bash
curl -X GET "https://api.tracertm.dev/v1/analysis/shortest-path?project_id=proj_123&source_id=item_req_001&target_id=item_test_005" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### Response

```json
{
  "exists": true,
  "distance": 3,
  "path": [
    "item_req_001",
    "item_design_001",
    "item_code_001",
    "item_test_005"
  ],
  "link_types": [
    "implements",
    "implements",
    "verified_by"
  ]
}
```

### Python Example

```python
# Find shortest path
path = client.analysis.shortest_path(
    project_id="proj_123",
    source_id="item_req_001",
    target_id="item_test_005"
)

if path.exists:
    print(f"Path found (distance: {path.distance}):")
    for i, item_id in enumerate(path.path):
        if i > 0:
            link_type = path.link_types[i-1]
            print(f"  --[{link_type}]--> {item_id}")
        else:
            print(f"  {item_id}")
else:
    print("No path found between items")
```

## Graph Neighbors

Get all neighbors of an item in the traceability graph.

### Endpoint

```
GET /api/v1/projects/{project_id}/graph/neighbors
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID |

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `item_id` | string | Yes | Item ID |
| `direction` | string | No | `in`, `out`, or `both` (default: `both`) |

### Request Example

```bash
curl -X GET "https://api.tracertm.dev/v1/projects/proj_123/graph/neighbors?item_id=item_req_001&direction=both" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### Response

```json
{
  "project_id": "proj_123",
  "item_id": "item_req_001",
  "direction": "both",
  "neighbors": [
    {
      "id": "link_abc123",
      "item_id": "item_test_001",
      "link_type": "verified_by",
      "direction": "out"
    },
    {
      "id": "link_def456",
      "item_id": "item_design_001",
      "link_type": "implements",
      "direction": "in"
    }
  ],
  "total": 2
}
```

### Python Example

```python
# Get neighbors
neighbors = client.graph.neighbors(
    project_id="proj_123",
    item_id="item_req_001",
    direction="both"
)

print(f"Total neighbors: {neighbors.total}")
for neighbor in neighbors.neighbors:
    print(f"  {neighbor.item_id} ({neighbor.direction}, {neighbor.link_type})")
```

## Use Cases

### 1. Change Impact Analysis

Before modifying a requirement, analyze what will be affected:

```python
# Analyze impact before change
impact = client.analysis.impact("item_req_001", "proj_123")

print(f"Changing this requirement will affect {impact.total_affected} items:")
for item in impact.affected_items:
    print(f"  - {item.title}")
```

### 2. Dependency Validation

Check for cycles before creating links:

```python
# Check for cycles
cycles = client.analysis.detect_cycles("proj_123")

if cycles.has_cycles:
    print("Warning: Cycles detected. Review dependencies.")
    # Prevent link creation or alert user
```

### 3. Traceability Verification

Verify traceability paths exist:

```python
# Check if requirement is traced to test
path = client.analysis.shortest_path(
    project_id="proj_123",
    source_id="item_req_001",
    target_id="item_test_001"
)

if path.exists:
    print(f"Traceability verified (path length: {path.distance})")
else:
    print("Warning: No traceability path found")
```

## Best Practices

### 1. Cache Analysis Results

Analysis can be expensive. Cache results when appropriate:

```python
from functools import lru_cache

@lru_cache(maxsize=100)
def get_cached_impact(item_id, project_id):
    return client.analysis.impact(item_id, project_id)
```

### 2. Batch Analysis

For multiple items, consider batch processing:

```python
items_to_analyze = ["item_req_001", "item_req_002", "item_req_003"]

for item_id in items_to_analyze:
    impact = client.analysis.impact(item_id, "proj_123")
    print(f"{item_id}: {impact.total_affected} affected items")
```

### 3. Monitor Cycle Detection

Regularly check for cycles:

```python
# Daily cycle check
cycles = client.analysis.detect_cycles("proj_123")

if cycles.has_cycles:
    send_alert(f"Cycles detected: {cycles.total_cycles}")
```

## Error Responses

### Item Not Found

```json
{
  "error": {
    "code": "not_found",
    "message": "Item not found"
  }
}
```

### Project Access Denied

```json
{
  "error": {
    "code": "forbidden",
    "message": "Project access denied"
  }
}
```

## Related Documentation

- [Items API](./02-artifacts) - Manage items
- [Links API](./04-relationships) - Create relationships
- [Search API](./06-search) - Search items and links
