---
title: Reports API
description: Complete API reference for generating traceability matrices, coverage reports, and compliance documentation in TraceRTM
---

# Reports API

The Reports API generates traceability matrices, coverage reports, compliance documentation, and analytics exports. Reports can be generated synchronously for small datasets or asynchronously for large projects.

## Endpoints Overview

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/projects/{project_id}/reports` | List available reports |
| `POST` | `/v1/projects/{project_id}/reports` | Generate report |
| `GET` | `/v1/projects/{project_id}/reports/{report_id}` | Get report status/result |
| `GET` | `/v1/projects/{project_id}/reports/{report_id}/download` | Download report |
| `DELETE` | `/v1/projects/{project_id}/reports/{report_id}` | Delete report |
| `GET` | `/v1/projects/{project_id}/traceability-matrix` | Live traceability matrix |
| `GET` | `/v1/projects/{project_id}/coverage-summary` | Coverage summary |

---

## Report Types

| Type | Description | Output Formats |
|------|-------------|----------------|
| `traceability_matrix` | Item-to-item traceability table | PDF, Excel, CSV, HTML |
| `coverage_report` | Requirement coverage analysis | PDF, Excel, HTML |
| `test_execution` | Test run results and statistics | PDF, Excel, HTML |
| `compliance_report` | Standards compliance (ISO, FDA, etc.) | PDF, Word |
| `impact_analysis` | Change impact assessment | PDF, Excel |
| `audit_trail` | Change history for audit | PDF, Excel |
| `gap_analysis` | Missing links and orphan items | PDF, Excel |
| `custom` | Custom report from template | Various |

---

## The Report Object

```json
{
  "id": "report_abc123xyz",
  "project_id": "proj_abc123",
  "type": "traceability_matrix",
  "name": "Q4 2024 Traceability Matrix",
  "status": "completed",
  "format": "pdf",
  "parameters": {
    "source_types": ["requirement"],
    "target_types": ["test_case", "design"],
    "link_types": ["verified_by", "implements"],
    "include_orphans": true,
    "include_coverage": true
  },
  "result": {
    "file_size_bytes": 2458624,
    "page_count": 45,
    "row_count": 450,
    "download_url": "https://...",
    "expires_at": "2024-12-15T10:00:00Z"
  },
  "statistics": {
    "total_items": 450,
    "linked_items": 425,
    "orphan_items": 25,
    "coverage_percent": 94.4
  },
  "created_by": "user_manager123",
  "created_at": "2024-12-08T10:00:00Z",
  "completed_at": "2024-12-08T10:02:30Z"
}
```

### Report Status

| Status | Description |
|--------|-------------|
| `pending` | Report queued for generation |
| `processing` | Report generation in progress |
| `completed` | Report ready for download |
| `failed` | Report generation failed |
| `expired` | Download link expired |

---

## List Reports

Retrieve previously generated reports.

```http
GET /v1/projects/{project_id}/reports
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | string | — | Filter by report type |
| `status` | string | — | Filter by status |
| `created_after` | string | — | Created after ISO date |
| `created_before` | string | — | Created before ISO date |
| `sort` | string | `created_at` | Sort field |
| `order` | string | `desc` | Sort order |
| `limit` | integer | 20 | Results per page |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/reports?type=traceability_matrix&status=completed" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": [
    {
      "id": "report_abc123xyz",
      "type": "traceability_matrix",
      "name": "Q4 2024 Traceability Matrix",
      "status": "completed",
      "format": "pdf",
      "statistics": {
        "total_items": 450,
        "coverage_percent": 94.4
      },
      "created_at": "2024-12-08T10:00:00Z",
      "completed_at": "2024-12-08T10:02:30Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "has_next": false
  }
}
```

### SDK Examples

#### Python

```python
from tracertm import TraceRTMClient

client = TraceRTMClient(api_key="rtm_live_sk_...")

# List completed reports
reports = client.reports.list(
    project_id="proj_abc123",
    status="completed",
    type="traceability_matrix"
)

for report in reports.data:
    print(f"{report.name}: {report.statistics.coverage_percent}% coverage")
```

---

## Generate Report

Create a new report.

```http
POST /v1/projects/{project_id}/reports
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Report type |
| `name` | string | No | Report name |
| `format` | string | No | Output format (default: `pdf`) |
| `parameters` | object | No | Type-specific parameters |
| `async` | boolean | No | Force async generation |

### Traceability Matrix Parameters

```json
{
  "type": "traceability_matrix",
  "format": "pdf",
  "parameters": {
    "source_types": ["requirement"],
    "target_types": ["test_case", "design"],
    "link_types": ["verified_by", "implements"],
    "source_filter": {
      "status": {"in": ["approved", "in_review"]},
      "priority": {"in": ["critical", "high"]}
    },
    "include_orphans": true,
    "include_coverage": true,
    "group_by": "parent",
    "sort_by": "item_number"
  }
}
```

### Coverage Report Parameters

```json
{
  "type": "coverage_report",
  "format": "excel",
  "parameters": {
    "requirement_filter": {
      "type": "requirement",
      "status": "approved"
    },
    "coverage_types": ["verified_by", "validated_by"],
    "include_test_results": true,
    "test_run_id": "run_abc123",
    "breakdown_by": ["priority", "module"]
  }
}
```

### Test Execution Report Parameters

```json
{
  "type": "test_execution",
  "format": "pdf",
  "parameters": {
    "test_run_ids": ["run_abc123", "run_def456"],
    "include_steps": true,
    "include_defects": true,
    "include_attachments": false,
    "group_by": "status"
  }
}
```

### Compliance Report Parameters

```json
{
  "type": "compliance_report",
  "format": "pdf",
  "parameters": {
    "standard": "ISO-26262",
    "asil_level": "D",
    "include_evidence": true,
    "sections": ["requirements", "verification", "validation", "traceability"]
  }
}
```

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/reports" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "traceability_matrix",
    "name": "Sprint 24 Traceability Report",
    "format": "pdf",
    "parameters": {
      "source_types": ["requirement"],
      "target_types": ["test_case"],
      "link_types": ["verified_by"],
      "include_orphans": true,
      "include_coverage": true
    }
  }'
```

### Response (Sync - Small Report)

```json
{
  "data": {
    "id": "report_new123",
    "type": "traceability_matrix",
    "name": "Sprint 24 Traceability Report",
    "status": "completed",
    "format": "pdf",
    "result": {
      "file_size_bytes": 1245678,
      "page_count": 25,
      "download_url": "https://api.tracertm.dev/v1/projects/proj_abc123/reports/report_new123/download",
      "expires_at": "2024-12-15T10:00:00Z"
    },
    "statistics": {
      "total_items": 150,
      "linked_items": 140,
      "orphan_items": 10,
      "coverage_percent": 93.3
    },
    "created_at": "2024-12-08T10:00:00Z",
    "completed_at": "2024-12-08T10:00:15Z"
  }
}
```

### Response (Async - Large Report)

```json
{
  "data": {
    "id": "report_large123",
    "type": "compliance_report",
    "name": "FDA Compliance Report",
    "status": "processing",
    "format": "pdf",
    "estimated_completion_seconds": 120,
    "created_at": "2024-12-08T10:00:00Z"
  }
}
```

### SDK Examples

#### Python

```python
# Generate traceability matrix
report = client.reports.create(
    project_id="proj_abc123",
    type="traceability_matrix",
    name="Sprint 24 Traceability",
    format="pdf",
    parameters={
        "source_types": ["requirement"],
        "target_types": ["test_case"],
        "include_orphans": True
    }
)

if report.status == "completed":
    # Download immediately
    client.reports.download(
        project_id="proj_abc123",
        report_id=report.id,
        output_path="./traceability_report.pdf"
    )
else:
    # Wait for async completion
    report = client.reports.wait_for_completion(
        project_id="proj_abc123",
        report_id=report.id,
        timeout_seconds=300
    )
    client.reports.download(
        project_id="proj_abc123",
        report_id=report.id,
        output_path="./traceability_report.pdf"
    )
```

#### TypeScript

```typescript
// Generate report
const report = await client.reports.create({
  projectId: 'proj_abc123',
  type: 'traceability_matrix',
  name: 'Sprint 24 Traceability',
  format: 'pdf',
  parameters: {
    sourceTypes: ['requirement'],
    targetTypes: ['test_case'],
    includeOrphans: true
  }
});

if (report.status === 'completed') {
  // Download
  const buffer = await client.reports.download({
    projectId: 'proj_abc123',
    reportId: report.id
  });
  fs.writeFileSync('./report.pdf', buffer);
} else {
  // Wait for completion
  const completed = await client.reports.waitForCompletion({
    projectId: 'proj_abc123',
    reportId: report.id,
    timeoutSeconds: 300
  });
}
```

---

## Get Report

Retrieve report status and details.

```http
GET /v1/projects/{project_id}/reports/{report_id}
```

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/reports/report_abc123" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": {
    "id": "report_abc123xyz",
    "project_id": "proj_abc123",
    "type": "traceability_matrix",
    "name": "Q4 2024 Traceability Matrix",
    "status": "completed",
    "format": "pdf",
    "parameters": {
      "source_types": ["requirement"],
      "target_types": ["test_case"],
      "include_orphans": true
    },
    "result": {
      "file_size_bytes": 2458624,
      "page_count": 45,
      "download_url": "https://...",
      "expires_at": "2024-12-15T10:00:00Z"
    },
    "statistics": {
      "total_items": 450,
      "linked_items": 425,
      "orphan_items": 25,
      "coverage_percent": 94.4
    },
    "created_at": "2024-12-08T10:00:00Z",
    "completed_at": "2024-12-08T10:02:30Z"
  }
}
```

---

## Download Report

Download the generated report file.

```http
GET /v1/projects/{project_id}/reports/{report_id}/download
```

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/reports/report_abc123/download" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -o "traceability_report.pdf"
```

### Response

Returns the binary file content with appropriate Content-Type header.

---

## Live Traceability Matrix

Get real-time traceability matrix data (JSON format for UI rendering).

```http
GET /v1/projects/{project_id}/traceability-matrix
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `source_types` | string | — | Comma-separated source types |
| `target_types` | string | — | Comma-separated target types |
| `link_types` | string | — | Comma-separated link types |
| `source_filter` | string | — | JSON filter for sources |
| `limit` | integer | 100 | Max rows |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/traceability-matrix?source_types=requirement&target_types=test_case" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": {
    "sources": [
      {
        "id": "item_req_001",
        "item_number": "VCS-REQ-001",
        "title": "Sensor processing timing",
        "status": "approved",
        "priority": "critical"
      },
      {
        "id": "item_req_002",
        "item_number": "VCS-REQ-002",
        "title": "Error handling",
        "status": "approved",
        "priority": "high"
      }
    ],
    "targets": [
      {
        "id": "item_tc_001",
        "item_number": "VCS-TC-001",
        "title": "Timing test",
        "status": "approved"
      },
      {
        "id": "item_tc_002",
        "item_number": "VCS-TC-002",
        "title": "Error test",
        "status": "approved"
      }
    ],
    "matrix": {
      "item_req_001": {
        "item_tc_001": {"linked": true, "link_type": "verified_by", "link_id": "link_001"},
        "item_tc_002": {"linked": false}
      },
      "item_req_002": {
        "item_tc_001": {"linked": false},
        "item_tc_002": {"linked": true, "link_type": "verified_by", "link_id": "link_002"}
      }
    },
    "statistics": {
      "total_sources": 2,
      "total_targets": 2,
      "linked_cells": 2,
      "coverage_percent": 100.0
    }
  }
}
```

### SDK Examples

#### Python

```python
matrix = client.reports.traceability_matrix(
    project_id="proj_abc123",
    source_types=["requirement"],
    target_types=["test_case"]
)

print(f"Coverage: {matrix.statistics.coverage_percent}%")

# Check specific cell
for source in matrix.sources:
    for target in matrix.targets:
        cell = matrix.matrix[source.id].get(target.id, {})
        if cell.get("linked"):
            print(f"{source.item_number} → {target.item_number}")
```

---

## Coverage Summary

Get quick coverage statistics.

```http
GET /v1/projects/{project_id}/coverage-summary
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `requirement_filter` | string | — | JSON filter for requirements |
| `group_by` | string | — | Group by: `type`, `priority`, `status`, `module` |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/coverage-summary?group_by=priority" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": {
    "project_id": "proj_abc123",
    "overall": {
      "total_requirements": 450,
      "covered_requirements": 425,
      "orphan_requirements": 25,
      "coverage_percent": 94.4,
      "total_tests": 380,
      "tests_with_results": 350,
      "pass_rate": 92.0
    },
    "by_priority": {
      "critical": {
        "total": 50,
        "covered": 50,
        "coverage_percent": 100.0,
        "pass_rate": 98.0
      },
      "high": {
        "total": 150,
        "covered": 148,
        "coverage_percent": 98.7,
        "pass_rate": 95.0
      },
      "medium": {
        "total": 200,
        "covered": 187,
        "coverage_percent": 93.5,
        "pass_rate": 90.0
      },
      "low": {
        "total": 50,
        "covered": 40,
        "coverage_percent": 80.0,
        "pass_rate": 85.0
      }
    },
    "uncovered_items": [
      {
        "id": "item_req_445",
        "item_number": "VCS-REQ-445",
        "title": "Logging configuration",
        "priority": "low"
      }
    ],
    "generated_at": "2024-12-08T10:00:00Z"
  }
}
```

### SDK Examples

#### Python

```python
coverage = client.reports.coverage_summary(
    project_id="proj_abc123",
    group_by="priority"
)

print(f"Overall coverage: {coverage.overall.coverage_percent}%")
print(f"Pass rate: {coverage.overall.pass_rate}%")

for priority, stats in coverage.by_priority.items():
    print(f"  {priority}: {stats.coverage_percent}% ({stats.total} items)")
```

---

## Error Responses

### Report Not Found

```json
{
  "error": {
    "code": "REPORT_NOT_FOUND",
    "message": "Report 'report_invalid' not found",
    "status": 404
  }
}
```

### Report Generation Failed

```json
{
  "error": {
    "code": "REPORT_GENERATION_FAILED",
    "message": "Report generation failed",
    "status": 500,
    "details": {
      "reason": "Template rendering error",
      "report_id": "report_failed123"
    }
  }
}
```

### Download Expired

```json
{
  "error": {
    "code": "REPORT_EXPIRED",
    "message": "Report download link has expired",
    "status": 410,
    "details": {
      "expired_at": "2024-12-15T10:00:00Z",
      "suggestion": "Generate a new report"
    }
  }
}
```

---

## Related Documentation

- [Requirements API](/docs/api-reference/rest-api/endpoints/requirements) - Item management
- [Tests API](/docs/api-reference/rest-api/endpoints/tests) - Test execution
- [Links API](/docs/api-reference/rest-api/endpoints/relationships) - Traceability links
- [Webhooks API](/docs/api-reference/rest-api/endpoints/webhooks) - Report completion notifications
