# Organization Statistics

Census provides organization-level inventory statistics via the `stats` command. This gives a bird's-eye view of your attestation activity without listing individual files.

## Basic usage

```bash
# Human-readable output
census stats

# Machine-readable JSON
census stats --json
```

Requires an API key with `batch` scope.

## Output

### Human-readable

```
Organization Inventory Statistics
  Total claims:  15,420
  Unique hashes: 12,800
  First claim:   2025-01-15T10:00:00Z
  Last claim:    2026-03-18T14:30:00Z

  Monthly breakdown:
    2026-01: 1,200
    2026-02: 1,350
    2026-03: 980
```

### JSON

```json
{
  "org_id_hash": "abc123...",
  "total_claims": 15420,
  "unique_hashes": 12800,
  "first_claim": "2025-01-15T10:00:00Z",
  "last_claim": "2026-03-18T14:30:00Z",
  "claims_by_month": {
    "2026-01": 1200,
    "2026-02": 1350,
    "2026-03": 980
  }
}
```

## Use cases

- **Audit trail**: Verify that attestation volumes match expected scan schedules.
- **Capacity planning**: Monitor monthly growth to anticipate API usage.
- **Compliance reporting**: Prove that file inventories are being maintained on a regular basis (NIS2, DORA).
- **Anomaly detection**: A sudden spike or drop in claims may indicate unauthorized scans or system failures.

## Error handling

If the API key lacks the required scope, Census exits with code 1 and reports the error:

```bash
census stats --json
# {"error": "Forbidden: API key does not have 'batch' scope"}
```

Retry logic applies to transient failures (429, 5xx). See [retry-and-resilience.md](retry-and-resilience.md).
