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

# Audit and compliance

> How Tracer maintains audit trails for SOX/GLBA compliance and how to query validation history.

Tracer maintains a complete, immutable audit trail of all validation decisions. This guide explains how the audit system works and how to query validation history for compliance reporting.

## Compliance overview

***

Tracer is designed to meet the audit requirements of financial regulations including:

| Regulation                    | Requirement                                 | How Tracer complies                            |
| ----------------------------- | ------------------------------------------- | ---------------------------------------------- |
| **SOX** (Sarbanes-Oxley)      | Complete audit trail of financial decisions | Every validation is recorded with full context |
| **GLBA** (Gramm-Leach-Bliley) | Protection of customer financial data       | Data encrypted at rest and in transit          |
| **General audit**             | Ability to reconstruct decisions            | Immutable records with input/output snapshots  |

***

## Audit trail architecture

***

Tracer records every validation decision with full context for compliance and investigation.

### What gets recorded

Every validation creates an immutable audit record containing:

| Data                  | Description                                  |
| --------------------- | -------------------------------------------- |
| **Request snapshot**  | Complete input payload as received           |
| **Response snapshot** | Full response including decision and details |
| **Decision**          | ALLOW, DENY, or REVIEW                       |
| **Reason**            | Why the decision was made                    |
| **Evaluated rules**   | All rules that were evaluated                |
| **Matched rules**     | Rules that triggered (if any)                |
| **Limit details**     | Usage information for checked limits         |
| **Processing time**   | How long validation took                     |
| **Timestamp**         | When the validation occurred                 |

### Immutability guarantees

Audit records are **write-once**:

* Records cannot be modified after creation
* Records cannot be deleted (except by retention policy)
* Each record has a unique validation ID for reference

<Note>
  The audit trail is designed for compliance audits. You can reconstruct exactly what happened for any validation, even years later.
</Note>

***

## Data retention

***

Tracer retains data according to regulatory requirements and operational needs.

### Retention periods

| Data type                   | Retention period | Reason                          |
| --------------------------- | ---------------- | ------------------------------- |
| **Validation records**      | 7 years minimum  | SOX/GLBA compliance requirement |
| **Rules (active/inactive)** | Indefinite       | Operational continuity          |
| **Rules (deleted)**         | Not retained     | Permanently removed             |
| **Limits**                  | Indefinite       | Operational continuity          |
| **Application logs**        | 90 days          | Debugging and troubleshooting   |

### Compliance considerations

* **SOX requirement:** Maintain records for 7 years from the date of the audit report
* **GLBA requirement:** Retain records demonstrating compliance with privacy rules
* **Data export:** Records can be exported for external audit systems

***

## Querying validation history

***

Use the `GET /v1/validations` endpoint to query historical validations.

### Basic query

```http theme={null}
GET /v1/validations
X-API-Key: {api_key}
```

Returns the most recent validations (last 90 days by default).

### Filtered query

```http theme={null}
GET /v1/validations?startDate=2026-01-01T00:00:00Z&endDate=2026-01-31T23:59:59Z&decision=DENY
X-API-Key: {api_key}
```

### Available filters

| Parameter         | Type    | Description                       |
| ----------------- | ------- | --------------------------------- |
| `startDate`       | RFC3339 | Start of date range (inclusive)   |
| `endDate`         | RFC3339 | End of date range (exclusive)     |
| `decision`        | enum    | Filter by ALLOW, DENY, or REVIEW  |
| `accountId`       | UUID    | Filter by account                 |
| `segmentId`       | UUID    | Filter by segment                 |
| `portfolioId`     | UUID    | Filter by portfolio               |
| `transactionType` | enum    | Filter by CARD, WIRE, PIX, CRYPTO |
| `matchedRuleId`   | UUID    | Filter by rule that matched       |
| `exceededLimitId` | UUID    | Filter by limit that was exceeded |

### Date format requirement

<Warning>
  Date parameters must use RFC3339 format with mandatory timezone. Date-only formats are rejected.
</Warning>

**Valid:**

```
startDate=2026-01-01T00:00:00Z
startDate=2026-01-01T00:00:00-03:00
```

**Invalid:**

```
startDate=2026-01-01  (rejected - missing time and timezone)
```

### Pagination

Results use cursor-based pagination. The response includes `nextCursor` and `hasMore` fields to navigate through results.

| Parameter | Default | Maximum | Description                              |
| --------- | ------- | ------- | ---------------------------------------- |
| `limit`   | 100     | 1000    | Results per page                         |
| `cursor`  | -       | -       | Pagination cursor from previous response |

<Note>
  When using cursor pagination, `sortBy` and `sortOrder` are fixed from the original query.
</Note>

### Sorting

```http theme={null}
GET /v1/validations?sortBy=createdAt&sortOrder=DESC
```

| Parameter   | Options                     | Default   |
| ----------- | --------------------------- | --------- |
| `sortBy`    | createdAt, processingTimeMs | createdAt |
| `sortOrder` | ASC, DESC                   | DESC      |

***

## Getting validation details

***

Retrieve complete details for a specific validation using `GET /v1/validations/{id}`.

The response contains everything needed to understand a validation decision:

* **Request snapshot**: The complete input payload as received
* **Response snapshot**: Full response including decision and reason
* **Evaluated rules**: All rules that were checked
* **Matched rules**: Rules that triggered (if any)
* **Limit details**: Usage information for checked limits
* **Timestamps**: When the validation occurred and processing time

***

## Compliance reporting scenarios

***

Common queries for audit and compliance reporting.

### Scenario 1: Audit investigation

"Why was this transaction denied on January 15th?"

```http theme={null}
GET /v1/validations/{id}
```

The response shows the exact request received, all rules evaluated, which rule or limit caused the denial, and the timestamp.

### Scenario 2: Monthly compliance report

"Show all denied transactions for corporate accounts in January"

```http theme={null}
GET /v1/validations?startDate=2026-01-01T00:00:00Z&endDate=2026-02-01T00:00:00Z&decision=DENY&segmentId=corporate-segment-uuid&limit=1000
```

### Scenario 3: Rule effectiveness analysis

"Which transactions were denied by a specific fraud rule?"

```http theme={null}
GET /v1/validations?matchedRuleId=fraud-rule-uuid&decision=DENY&limit=1000
```

### Scenario 4: Limit utilization review

"Which transactions exceeded spending limits this month?"

```http theme={null}
GET /v1/validations?startDate=2026-01-01T00:00:00Z&endDate=2026-02-01T00:00:00Z&exceededLimitId=daily-limit-uuid
```

***

## Best practices for compliance

***

Recommendations for maintaining audit readiness.

### Record keeping

* **Store validation IDs** in your transaction records for easy cross-reference
* **Log the requestId** you send to Tracer for correlation
* **Export regularly** if you need records in external audit systems

### Audit preparation

* **Test queries** before audit season to ensure you can retrieve needed data
* **Verify date ranges** work correctly with your timezone requirements
* **Document your retention policy** alignment with Tracer's 7-year retention

### Investigation workflow

When investigating a specific transaction:

1. **Find the validation ID** from your transaction logs or Tracer history
2. **Retrieve full details** using GET /v1/validations/{id}
3. **Review the request snapshot** to see what data was provided
4. **Check matched rules** to understand why the decision was made
5. **Verify limit status** if limits were involved

***

## Fail-open behavior and audit

***

Tracer uses a **configurable fail-open** approach by default:

| Scenario                         | Default behavior   | Audit record                          |
| -------------------------------- | ------------------ | ------------------------------------- |
| No rules match                   | ALLOW              | Recorded with reason "no\_match"      |
| Database temporarily unavailable | ALLOW with warning | Recorded if possible; alert generated |
| Evaluation timeout               | ALLOW with warning | Recorded with reason "timeout"        |

<Note>
  Fail-open behavior can be configured to fail-closed for high-security environments. Contact your administrator for configuration options.
</Note>

All decisions, including those made during degraded operation, are recorded in the audit trail when possible. If a decision cannot be recorded (catastrophic failure), alerts are generated for manual review.

***

## Quick reference

***

Key endpoints and retention information.

### Endpoints

| Operation        | Method | Endpoint               |
| ---------------- | ------ | ---------------------- |
| List validations | GET    | `/v1/validations`      |
| Get validation   | GET    | `/v1/validations/{id}` |

### Retention summary

| Data                | Retention  |
| ------------------- | ---------- |
| Validation records  | 7+ years   |
| Active rules/limits | Indefinite |
| Application logs    | 90 days    |