Data Model

The Neuramancer API is built around two main entities:

• Tenant: Organization or account that owns analyses and configurations
• Analysis: Image analysis request and its results

The diagrams below are organized by domain for readability.

flowchart LR
    T[Tenant] --> A[Analysis]
    A --> I[Input & Storage]
    A --> S[Inference & Results]
    S --> H[Heatmaps]
    
    style T fill:#9370db,stroke:#fff,stroke-width:2px,color:#000
    style A fill:#4a9eff,stroke:#fff,stroke-width:2px,color:#000
    style I fill:#90ee90,stroke:#fff,stroke-width:2px,color:#000
    style S fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000
    style H fill:#ff9090,stroke:#fff,stroke-width:2px,color:#000

---

Analysis

The Analysis document contains embedded sub-documents forming a hierarchical structure:

flowchart TD
    A[analysis] --> I[input]
    A --> S[inferenceStatus]
    
    I --> O[options]
    I --> SU[storageUrls]
    
    S --> R[result<br><small>when completed</small>]
    
    R --> RC[resultClass<br><small>always available</small>]
    R --> RSC[resultSubClasses<br><small>always available, optional</small>]
    R --> P[predictions<br><small>forensicReporting only</small>]
    R --> U[classUncertainties<br><small>forensicReporting only</small>]
    R --> CS[classSimilarities<br><small>forensicReporting only</small>]
    R --> AN[anomaly<br><small>forensicReporting only</small>]
    R --> H[heatmaps<br><small>forensicReporting only</small>]
    R --> REP[report<br><small>forensicReporting only</small>]
    
    H --> HSU[*StorageUrls]
    REP --> REPSU[pdfStorageUrls per language]

    style A fill:#4a9eff,stroke:#fff,stroke-width:2px,color:#000
    style R fill:#90ee90,stroke:#fff,stroke-width:2px,color:#000
    style RC fill:#87ceeb,stroke:#fff,stroke-width:2px,color:#000
    style RSC fill:#87ceeb,stroke:#fff,stroke-width:2px,color:#000
    style SU fill:#90ee90,stroke:#fff,stroke-width:2px,color:#000
    style HSU fill:#90ee90,stroke:#fff,stroke-width:2px,color:#000
    style REPSU fill:#90ee90,stroke:#fff,stroke-width:2px,color:#000
    style P fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000
    style U fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000
    style CS fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000
    style AN fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000
    style H fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000
    style REP fill:#ffd700,stroke:#fff,stroke-width:2px,color:#000

The root Analysis document with metadata and timestamps:

erDiagram
    analysis ||--|| "analysis.input" : contains
    analysis ||--|| "analysis.inferenceStatus" : contains

    analysis {
        ObjectId id PK "Unique identifier"
        ObjectId tenantId FK "Tenant reference"
        ObjectId projectId FK "Optional project"
        string name "Display name"
        string storageType "azure | s3"
        string type "Always 'image'"
        string comment "User notes"
        array tags "Classification tags"
        datetime createdDate "Creation timestamp"
        datetime updatedDate "Last modification"
        datetime deletedDate "Soft-delete timestamp"
    }

---

Input & Storage

Analysis input containing image metadata and storage URLs:

erDiagram
    "analysis.input" ||--|| "analysis.input.options" : contains
    "analysis.input" ||--|| "analysis.input.storageUrls" : has

    "analysis.input" {
        string format "jpg | png"
        string version "Schema version"
        int width "Image width (px, >64, ≤8192)"
        int height "Image height (px, >64, ≤8192)"
        string filename "Original filename"
    }

    "analysis.input.storageUrls" {
        string type "azure | s3"
        string objectKey "S3 object key, the second part after '/' is the file name in the bucket"
        string putUrl "Upload URL"
        string getUrl "Read URL"
        string deleteUrl "Delete URL"
        datetime expiresAt "ISO 8601 expiry timestamp"
    }

    "analysis.input.options" {
        string model "Model identifier"
        string decisionStrategy "Threshold strategy (default: 'default')"
        string tier "flagging | forensicReporting"
        int seed "Optional: Seed value (default: 1337)"
    }

NOTE: The analysis.input.options.tier field defaults to flagging.

---

Inference & Results

Inference processing status and classification results:

erDiagram
    "analysis.inferenceStatus" ||--o| "analysis.inferenceStatus.result" : "when completed"
    "analysis.inferenceStatus.result" ||--|| "result.predictions" : contains
    "analysis.inferenceStatus.result" ||--|| "result.classUncertainties" : contains
    "analysis.inferenceStatus.result" ||--|| "result.classSimilarities" : contains
    "analysis.inferenceStatus.result" ||--o| "result.anomaly" : contains
    "analysis.inferenceStatus.result" ||--o| "result.heatmaps" : contains
    "analysis.inferenceStatus.result" ||--o| "result.report" : contains

    "analysis.inferenceStatus" {
        string type "Model type (BD)"
        string version "Model version"
        string status "pending | processing | completed | failed"
        string statusMessage "Human-readable status"
        int retryCount "Retry attempts"
        datetime processingStartTime "Processing start"
        datetime processingFinishTime "Processing end"
    }

    "analysis.inferenceStatus.result" {
        string resultClass "0, 1, 2, 3 (real, fake, abstain, uncertain)"
        string resultSubClasses "0, 1, 2 (ai-generated, ai-manipulated, manipulated)"
        object predictions "Per-class probabilities (forensicReporting only)"
        object classUncertainties "Per-class uncertainty (forensicReporting only)"
        object classSimilarities "Per-class similarity (forensicReporting only)"
        object anomaly "Anomaly score/cluster/gini (forensicReporting only)"
        object heatmaps "Heatmap URLs (forensicReporting only)"
        object report "Localized report (forensicReporting only)"
    }

    "result.predictions" {
        float real "0.0 - 1.0"
        float fake "0.0 - 1.0"
        float compression "0.0 - 1.0"
    }

    "result.classUncertainties" {
        float real "Uncertainty measure"
        float fake "Uncertainty measure"
        float compression "Uncertainty measure"
    }

    "result.classSimilarities" {
        float realCompressed "Similarity score"
        float fakeCompressed "Similarity score"
    }

    "result.anomaly" {
        float score "Overall anomaly score 0.0-1.0"
        number numCluster "Number of anomaly clusters"
        float giniCoeff "Gini coefficient 0.0-1.0"
    }

---

Heatmaps

2D visualization heatmaps showing model attention regions are available as PNG files with presigned URLs (e.g. realHeatmapStorageUrls.getUrl). These heatmaps help interpret model decisions by highlighting areas influencing classification. They are exactly in the same dimensions as the input image for easy overlaying.

erDiagram
    "analysis.inferenceStatus.result" ||--|| "result.heatmaps" : contains
    "result.heatmaps" ||--|| "heatmap.storageUrls" : uses

    "result.heatmaps" {
        object realHeatmapStorageUrls "Real detection heatmap URLs"
        object fakeHeatmapStorageUrls "Fake detection heatmap URLs"
        object compressionHeatmapStorageUrls "Compression heatmap URLs"
        object anomalyHeatmapStorageUrls "Anomaly heatmap URLs"
    }

    "heatmap.storageUrls" {
        string type "azure | s3"
        string getUrl "Read URL"
        datetime expiresAt "ISO 8601 expiry timestamp"
    }

Heatmap Storage

All heatmaps use *HeatmapStorageUrls objects with presigned URLs for secure access. Should you need to re-fetch expired URLs, simply re-query the analysis via GET /v1/analysis?id=<analysisId>.

Field Reference

Analysis (Root)

Field	Type	Required	Description
id	ObjectId	Auto	Unique identifier
tenantId	ObjectId	Yes	Tenant reference
projectId	ObjectId	No	Project grouping (null if not assigned)
name	string	Yes	Display name (1-255 chars)
storageType	enum	Yes	azure | s3
type	enum	Yes	image
comment	string	No	User notes (max 500 chars)
tags	string[]	No	Classification tags
createdDate	datetime	Auto	ISO 8601 creation time
updatedDate	datetime	Auto	ISO 8601 last update (null if never updated)
deletedDate	datetime	Auto	ISO 8601 soft-delete time (null if not deleted)
createdByUserId	string	Auto	Immutable creator identifier. Stores the MongoDB user ObjectId string for app users, the API key UUID for API clients, or null for system-created records.
lastChangedByUserType	string	Auto	Actor type that made the last change (user, api, or system).
lastChangedByUserId	string	Auto	Identifier of the actor that made the last tracked client mutation. Stores the MongoDB user ObjectId string for app users, the API key UUID for API clients, or null for system updates.
lastChangedByUserName	string	Auto	Read-time projection of the user display name for lastChangedByUserId. Returned by analysis read endpoints when the last actor is a user and the user record has a name; otherwise null.

Analysis Input

Path: analysis.input

Field	Type	Required	Description
format	enum	Yes	jpg | png
version	enum	Yes	v1
width	integer	Yes	Image width in pixels (>64, ≤8192)
height	integer	Yes	Image height in pixels (>64, ≤8192)
filename	string	Yes	Original filename
storageUrls	StorageUrls	Yes	S3/Azure storage URLs for input file
options	object	Yes	Analysis options

Storage URLs

Path: analysis.input.storageUrls, analysis.inferenceStatus.result.report.<lang>.pdfStorageUrls, analysis.inferenceStatus.result.heatmaps.*HeatmapStorageUrls

The StorageUrls object provides presigned URLs for file access across both S3 and Azure storage backends:

Field	Type	Required	Description
type	enum	Yes	azure | s3
objectKey	string	Yes	S3 object key used to regenerate presigned URLs on expiry
putUrl	string	Yes	Presigned URL for uploading
getUrl	string	Yes	Presigned URL for downloading
deleteUrl	string	Yes	Presigned URL for deletion
expiresAt	string	Yes	ISO 8601 date string when the URLs expire

Analysis Options

Path: analysis.input.options

Field	Type	Default	Description
model	string	Required	Model identifier (e.g., nais-image-latest)
decisionStrategy	enum	Required	default | pedantic | relaxed
tier	enum	flagging	flagging | forensicReporting - determines what data GET /v1/analysis returns and how the analysis is billed. flagging returns only the result class. forensicReporting returns full forensic data (heatmaps, predictions, forensic texts, PDF report). See Cost Model.
seed	integer	1337	Seed for random number generation in inference. A fixed seed (default 1337) produces stable, reproducible results due to seeded random behaviour. Varying the seed introduces non-determinism, yielding more probabilistic results across runs. Also affects the text generation.

Decision Strategies

Path: analysis.input.options.decisionStrategy

The decisionStrategy parameter controls decision strategy the “uncertain” / “abstain” ratio. It doesn’t change the classification of real vs. fake.

Strategy	Description	Use Case
default	Balanced approach for general use	Most common scenarios
pedantic	More abstain and uncertain decisions to reduce false positives/negatives	Investigative Journalism with low tolerance for errors, Legal, Regulatory cases
relaxed	Less abstain and uncertain decisions to increase sensitivity	Scenarios where missing fakes is worse than false alarms (e.g. oversight, content moderation, fact-checking)

Inference Status

Path: analysis.inferenceStatus

Field	Type	Description
type	enum	Model type identifier: image
version	string	Model version (e.g., latest)
status	enum	pending | processing | completed | failed
statusMessage	string	Human-readable status message
retryCount	integer	Number of retry attempts
processingStartTime	datetime	ISO 8601 processing start
processingFinishTime	datetime	ISO 8601 processing end
result	object	Inference result (present when status=completed)

Inference Result

Path: analysis.inferenceStatus.result

The fields available in the inference result depend on the tier option used when creating the analysis:

GET /v1/analysis returns all fields below, but fields marked forensicReporting only are null for flagging-tier analyses.

Field	Type	Description
resultClass	number	0 real | 1 fake | 2 abstain | 3 uncertain
resultSubClasses	Array<number>	Sub-classification: 0 ai-generated | 1 ai-manipulated | 2 manipulated (empty set is allowed)
predictions	object	Probability scores per class (nullable) - forensicReporting only
classUncertainties	object	Uncertainty measures per class (nullable) - forensicReporting only
classSimilarities	object	Similarity scores between classes (nullable) - forensicReporting only
anomaly	object	Anomaly detection results: score, numCluster, giniCoeff (nullable) - forensicReporting only
heatmaps	object	Visualization URLs (see Heatmaps) - forensicReporting only
report	object	Localized report outputs keyed by language (de, en), each containing pdfStorageUrls, summary, forensic, heatmapIntro, heatmap, conclusion (nullable) - forensicReporting only

Tier-based Field Visibility

GET /v1/analysis returns tier-appropriate data. For flagging-tier analyses, only resultClass and resultSubClasses are populated - all other forensic fields are null. For forensicReporting-tier analyses, the full inference result is returned. This enables cost-efficient workflows where you screen at scale with flagging and only pay for full forensic data when needed. See Cost Model.

Report

The Report type contains localized report outputs keyed by language (de, en), each containing pdfStorageUrls, summary, forensic, heatmapIntro, heatmap, conclusion (nullable) - forensicReporting only:

Report = { [lang: string]: {
  pdfStorageUrls: string[],
  summary: string,
  forensic: string,
  heatmapIntro: string,
  heatmap: string,
  conclusion: string
} }

Example:

{
  "en": {
    "pdfStorageUrls": [...],
    "summary": "This image shows strong indicators of manipulation.",
    "forensic": "Forensic analysis details here.",
    "heatmapIntro": "Heatmap introduction here.",
    "heatmap": "Heatmap visualization here.",
    "conclusion": "Conclusion here."
  },
  "de": {
    "pdfStorageUrls": [...],
    "summary": "Dieses Bild zeigt starke Anzeichen für Manipulation.",
    "forensic": "Forensische Analyse-Details hier.",
    "heatmapIntro": "Einführung in die Heatmap hier.",
    "heatmap": "Heatmap-Visualisierung hier.",
    "conclusion": "Schlussfolgerung hier."
  }
}

The following language codes are supported (lang) as ISO2 codes:

ISO2 Code	Language
en	English
de	German

Note: Additional languages will be added in upcoming updates.

Predictions

Path: analysis.inferenceStatus.result.predictions

Field	Type	Range	Description
real	float	0.0-1.0	Probability image is authentic
fake	float	0.0-1.0	Probability image is manipulated
compression	float	0.0-1.0	Compression artifact score

Class Uncertainties

Path: analysis.inferenceStatus.result.classUncertainties

Field	Type	Description
real	float	Uncertainty measure for real classification
fake	float	Uncertainty measure for fake classification
compression	float	Uncertainty measure for compression detection

Class Similarities

Path: analysis.inferenceStatus.result.classSimilarities

Field	Type	Description
realCompressed	float	Similarity score between real and compressed features
fakeCompressed	float	Similarity score between fake and compressed features

Anomaly

Path: analysis.inferenceStatus.result.anomaly

Anomaly detection results, separate from the per-class predictions. null on error or for flagging-tier analyses.

Field	Type	Range	Description
score	float | null	0.0-1.0	Overall anomaly score
numCluster	number | null	-	Number of detected anomaly clusters
giniCoeff	float | null	0.0-1.0	Gini coefficient of the spatial anomaly distribution

Heatmaps

Path: analysis.inferenceStatus.result.heatmaps

These heatmaps help interpret model decisions by highlighting areas influencing classification. They are exactly in the same dimensions as the input image for easy overlaying.

Heatmap visualization URLs for each detection type:

Field	Type	Description
realHeatmapStorageUrls	StorageUrls	Storage URLs for real heatmap
fakeHeatmapStorageUrls	StorageUrls	Storage URLs for fake heatmap
compressionHeatmapStorageUrls	StorageUrls	Storage URLs for compression heatmap
anomalyHeatmapStorageUrls	StorageUrls	Storage URLs for anomaly heatmap

Available heatmaps: real, fake, compression, anomaly

Report

Path: analysis.inferenceStatus.result.report

The report object contains localized report outputs keyed by supported language (de, en). It is null for flagging-tier analyses, if not yet generated, or on error. Each language object has the following structure:

Path: analysis.inferenceStatus.result.report.<lang>

Field	Type	Description
pdfStorageUrls	StorageUrls | null	Storage URLs for the localized PDF report
summary	string	Short localized summary of the forensic verdict
forensic	string	Localized detailed forensic explanation
heatmapIntro	string	Localized introductory text for the heatmaps section
heatmap	object	Localized explanatory text per heatmap type (see below)
conclusion	string	Localized concluding verdict

Path: analysis.inferenceStatus.result.report.<lang>.heatmap

Field	Type	Description
real	string	Explanation text for the authenticity heatmap
fake	string	Explanation text for the AI/synthetic heatmap
compressed	string	Explanation text for the compression heatmap
anomaly	string	Explanation text for the anomaly heatmap

---

Tenant

The Tenant entity represents an organization or account within the Neuramancer system. Each tenant has its own analyses, storage configuration, API keys, and webhook settings.

erDiagram
    tenant ||--o{ analysis : "owns"
    tenant ||--o{ apiKey : "has"
    tenant ||--o| storageConfigMap : "configured with"
    storageConfigMap ||--o| s3Config : "contains"
    storageConfigMap ||--o| azureConfig : "contains"
    
    tenant {
        ObjectId id PK "Unique identifier"
        string name "Tenant name (unique)"
        datetime createdDate "Creation timestamp"
        string webhookUrl "Webhook endpoint URL"
        string storageType "azure | s3"
        object storageConfig "Storage config map (optional)"
        array apiKeys "API key objects"
    }

    apiKey {
        string name "Descriptive name"
        string uuid "Unique identifier"
        datetime createdDate "Creation timestamp"
        datetime expiryDate "Expiration date"
        string secret "API key value (masked after first read)"
    }
    
    storageConfigMap {
        object s3 "S3 configuration (optional)"
        object azure "Azure configuration (optional)"
    }
    
    s3Config {
        string endpoint "S3 endpoint URL"
        int port "S3 port number"
        boolean useSSL "S3 use SSL"
        string bucketName "S3 bucket name"
        string region "S3 region"
        string accessKeyId "S3 access key"
        string secretAccessKey "S3 secret key"
        int presignedUrlExpirySeconds "URL expiry (≥600s)"
    }
    
    azureConfig {
        string containerName "Azure container"
        string connectionString "Azure connection"
    }

Tenant (Root)

Field	Type	Required	Description
id	ObjectId	Auto	Unique tenant identifier (immutable)
name	string	Yes	Tenant name (unique identifier, updatable via PUT /v1/tenant)
createdDate	datetime	Auto	ISO 8601 tenant creation timestamp
webhookUrl	string	No	URL to call for analysis status changes (max 2048 chars, updatable via PUT /v1/tenant)
storageType	enum	No	azure | s3 (updatable via PUT /v1/tenant)
storageConfig	StorageConfigMap	No	Storage authentication configuration (see below, updatable via PUT /v1/tenant). If not set, Neuramancer default storage is used.
apiKeys	array	Auto	Array of API key objects (read-only via GET, managed via dedicated API key endpoints)
isTrial	boolean	No	System-managed trial flag. When true, only approved trial images (real.jpg, fake.jpg) can be analyzed via /v1/analysis/start. Read-only — cannot be changed via API.

API Key Fields

Path: tenant.apiKeys[]

Field	Type	Required	Description
name	string	Yes	Descriptive name for the key
uuid	string	Auto	Unique identifier for the API key
createdDate	datetime	Auto	ISO 8601 creation timestamp
expiryDate	datetime	Yes	ISO 8601 expiration timestamp
secret	string	Auto	API key secret (format: sk-<tenantTag>-<random>, masked after first retrieval)

Storage Configuration

Path: tenant.storageConfig

Tenants can configure blob storage for storing analysis images and results. The storageConfig field is a map containing optional s3 and/or azure sub-objects:

{
  "storageConfig": {
    "s3": { /* S3Config */ },
    "azure": { /* AzureConfig */ }
  }
}

S3 Configuration

Path: tenant.storageConfig.s3

For S3-compatible storage (AWS S3, Hetzner Object Storage, MinIO):

Field	Type	Required	Description
endpoint	string	Yes	S3 endpoint URL (e.g., s3.eu-central-1.amazonaws.com)
port	integer	Yes	S3 port number (typically 443 for HTTPS)
useSSL	boolean	Yes	Whether to use SSL/TLS for connections
bucketName	string	Yes	S3 bucket name
region	string	Yes	AWS region code (e.g., eu-central-1)
accessKeyId	string	Yes	S3 access key ID
secretAccessKey	string	Yes	S3 secret access key (masked in responses)
presignedUrlExpirySeconds	integer	No	Presigned URL expiry time in seconds (≥ 600, default: 7 days)
corsAllowedOrigins	string[]	No	List of allowed CORS origins for browser-based uploads (e.g. ["https://app.example.com"]). Defaults to Neuramancer app origins when not set.

Azure Configuration

Path: tenant.storageConfig.azure

For Azure Blob Storage:

Field	Type	Required	Description
containerName	string	Yes	Azure Blob Storage container name
connectionString	string	Yes	Azure Storage account connection string (masked in responses)

Configuration: Managed via Tenant Management API using PUT /v1/tenant. See Blob Storage Management for detailed configuration guide.

Presigned URL Refresh

Presigned URLs expire after the configured time period. To get fresh URLs, simply retrieve the analysis again via GET /v1/analysis. The system automatically regenerates presigned URLs with updated expiration timestamps.

Storage Migration

Changing storage configuration while analyses are in progress will cause failures. Presigned URLs cannot be refreshed if storage configuration changes. See Blob Storage Management for safe migration procedures.

Tenant Updates via PUT /v1/tenant

When updating a tenant via PUT /v1/tenant, the following fields are read-only and cannot be modified:

• id - Immutable identifier
• apiKeys - Must be managed via dedicated API key endpoints
• analytics - Read-only analytics data
• isTrial - System-managed trial flag

Attempting to update these fields will have no effect; they are stripped from the request payload.

Webhook Configuration

Path: tenant.webhookUrl

Tenants can configure a single webhook URL to receive notifications when analysis status changes. See Webhooks for detailed webhook documentation.

Webhook Payload: When an analysis status changes, the webhook receives:

{
  "analysisId": "60f7b3b3e1b3f4001f8b4567",
  "tenantId": "60f7b3b3e1b3f4001f8b1234",
  "name": "my-analysis",
  "status": "completed",
  "timestamp": "2026-03-02T10:30:00.000Z",
  "resultClass": 0,
  "resultSubClasses": [1],
  "processingStartTime": "2026-03-02T10:29:55.000Z",
  "processingFinishTime": "2026-03-02T10:30:00.000Z"
}

Field	Type	Description
analysisId	string	MongoDB ObjectId of the analysis
tenantId	string	MongoDB ObjectId of the tenant
name	string	Name/filename of the analysis
status	enum	pending | processing | completed | failed
timestamp	string	ISO 8601 timestamp when the webhook was triggered
resultClass	number	0 real | 1 fake | 2 abstain | 3 uncertain
resultSubClasses	Array<number>	Sub-classification: 0 ai-generated | 1 ai-manipulated | 2 manipulated (empty set is allowed)
processingStartTime	string | null	ISO 8601 timestamp when processing started, or null
processingFinishTime	string | null	ISO 8601 timestamp when processing finished, or null

See Webhooks for detailed webhook documentation.

---

Tenant Report

The Tenant Report contains daily analytics metrics for each tenant. Reports are generated by a scheduled job that runs every 24 hours and track successful processing, user interactions, impediments, and quality indicators.

erDiagram
    tenant ||--o{ "tenant_report" : "owns"
    "tenant_report" ||--|| "processing_metrics" : contains
    "tenant_report" ||--|| "user_interaction_metrics" : contains
    "tenant_report" ||--|| "impediment_metrics" : contains
    "tenant_report" ||--|| "quality_indicators" : contains
    "tenant_report" ||--|| "processing_durations" : contains
    
    "processing_metrics" ||--|| "processing_by_type" : contains
    "processing_metrics" ||--|| "processing_by_result" : contains
    "processing_metrics" ||--|| "processing_by_model_type_and_tier" : contains
    "processing_by_model_type_and_tier" ||--|| "processing_by_tier" : contains
    "processing_durations" ||--|| "processing_duration_by_model_type_and_mode" : contains
    "processing_duration_by_model_type_and_mode" ||--|| "processing_duration_by_parallelism" : contains

    tenant_report {
        ObjectId id PK "Unique identifier"
        ObjectId tenantId FK "Tenant reference"
        datetime updatedAt "Last update timestamp"
        datetime startTime "Period start (UTC)"
        datetime endTime "Period end (UTC)"
        integer queuedAnalyses "Pending analyses at report time"
        object successfulProcessing "Processing metrics"
        object userInteraction "User interaction metrics"
        object impediments "Impediment metrics"
        object qualityIndicators "Quality indicators"
        object processingDurations "Processing durations"
    }

    processing_by_type {
        integer api "API-triggered analyses"
        integer app "App-triggered analyses"
        integer total "Total analyses (API + App)"
    }

    processing_by_result {
        integer fake "Deepdeepfake detections"
        integer real "Real detections"
        integer uncertain "Uncertain results"
        integer abstain "Abstained results"
        integer total "Total results"
        float confidenceScore "Confidence metric (0-1)"
    }

    processing_by_model_type_and_tier {
        object image "ProcessingByTier for image"
    }

    processing_by_tier {
        integer forensicReporting "forensicReporting tier count"
        integer flagging "flagging tier count"
    }

    processing_metrics {
        object byType "Processing by trigger type"
        object byResult "Processing by result class"
        object byModelTypeAndTier "Processing by model type and tier"
    }

    user_interaction_metrics {
        integer appLogins "Frontend app logins"
    }

    impediment_metrics {
        integer processingErrors "Failed analyses"
        integer retries "Retried analyses"
    }

    quality_indicators {
        float errorRatePercent "Error rate (%)"
        float backpressurePercent "Queue pressure (%)"
    }

    processing_durations {
        object byModelTypeAndParallelism "Durations by model type and mode"
    }

    processing_duration_by_model_type_and_mode {
        object image "ProcessingDurationByParallelism for image"
    }

    processing_duration_by_parallelism {
        float single "Avg single processing duration (min)"
        float bulk "Avg bulk processing duration (min)"
    }

Tenant Report (Root)

Path: /v1/tenant/report

Accessed via the GET /v1/tenant/report endpoint:

Field	Type	Required	Description
id	ObjectId	Auto	Unique report identifier
tenantId	ObjectId	Yes	Reference to the tenant
updatedAt	datetime	Yes	ISO 8601 timestamp when report was last updated
startTime	datetime	Yes	ISO 8601 start time of reporting period (UTC midnight)
endTime	datetime	Yes	ISO 8601 end time of reporting period (UTC midnight)
queuedAnalyses	integer	Yes	Number of pending (non-completed, non-failed) analyses at report generation time. Not included in cost calculations.
successfulProcessing	ProcessingMetrics	Yes	Metrics aggregating successful analyses by type, result, and tier
userInteraction	UserInteractionMetrics	Yes	User interaction metrics (e.g., app logins)
impediments	ImpedimentMetrics	Yes	Metrics for failed and retried analyses
qualityIndicators	QualityIndicators	Yes	System health metrics (error rate, backpressure)
processingDurations	ProcessingDurations	Yes	Average processing times by model type and parallelism mode

Processing Metrics

Path: tenant_report.successfulProcessing

Aggregates successful analyses by trigger type, result class, and tier:

Field	Type	Description
byType	ProcessingByType	Analyses categorized by how they were triggered (API vs App)
byResult	ProcessingByResult	Analyses categorized by their result classification
byModelTypeAndTier	ProcessingByModelTypeAndTier	Analyses categorized by model type and analysis tier

Processing by Type

Path: tenant_report.successfulProcessing.byType

Tracks successful analyses by trigger mechanism:

Field	Type	Range	Description
api	integer	≥ 0	Number of analyses triggered via API during the reporting period. Used to estimate costs based on API usage patterns.
app	integer	≥ 0	Number of analyses triggered via frontend App during the reporting period. Used to estimate costs based on frontend usage patterns.
total	integer	≥ 0	Sum of API and App analyses. Used to estimate total costs and for overall usage allocation.

Processing by Result

Path: tenant_report.successfulProcessing.byResult

Tracks successful analyses by classification result:

Field	Type	Range	Description
fake	integer	≥ 0	Number of analyses detected as fake (“Fake”) during the reporting period
real	integer	≥ 0	Number of analyses detected as real (“Echt”) during the reporting period
uncertain	integer	≥ 0	Number of analyses with uncertain (“Unsicher”) result during the reporting period
abstain	integer	≥ 0	Number of analyses with abstain (“Enthaltung”) result during the reporting period
total	integer	≥ 0	Total determinate results (fake + real + uncertain + abstain)
confidenceScore	float	0.0-1.0	Confidence metric calculated as round(((fake + real) / total) * 100) / 100. Indicates the proportion of determinate results. Values closer to 1.0 indicate higher confidence; 0.0 means no determinate results.

User Interaction Metrics

Path: tenant_report.userInteraction

Tracks user activities that may correlate with processing:

Field	Type	Description
appLogins	integer	Number of successful logins to the frontend application during the reporting period. Can be used to correlate user activity with processing activity and for cost allocation based on user interactions.

Impediment Metrics

Path: tenant_report.impediments

Tracks analysis failures and retries that may affect quality:

Field	Type	Description
processingErrors	integer	Number of analyses that failed during the reporting period. Used to monitor system quality and for cost allocation based on error rates.
retries	integer	Number of analyses that were retried during the reporting period (analyses with retryCount > 0). Used to monitor system reliability and for cost allocation based on retry rates.

Quality Indicators

Path: tenant_report.qualityIndicators

Metrics used to monitor system health and inform cost allocation:

Field	Type	Range	Description
errorRatePercent	float	0-100	Error rate percentage calculated as (failed / (completed + failed)) * 100. Used to monitor overall quality and system reliability.
backpressurePercent	float	0-100	System load percentage calculated as (pending / (completed + pending)) * 100. Used to monitor queue depth and system capacity. High values indicate backlog buildup.

Processing by Model Type and Tier

Path: tenant_report.successfulProcessing.byModelTypeAndTier

Breaks down successful analyses by model type and analysis tier:

Field	Type	Description
image	ProcessingByTier	Tier breakdown for image analyses

Processing by Tier

Path: tenant_report.successfulProcessing.byModelTypeAndTier.image

Field	Type	Description
forensicReporting	integer	Number of analyses run with forensicReporting tier
flagging	integer	Number of analyses run with flagging tier

Processing Durations

Path: tenant_report.processingDurations

Average processing times grouped by model type and parallelism mode:

Field	Type	Description
byModelTypeAndParallelism	ProcessingDurationByModelTypeAndMode	Durations grouped by model type and processing parallelism (single/bulk)

Processing Duration by Model Type and Mode

Path: tenant_report.processingDurations.byModelTypeAndParallelism

Field	Type	Description
image	ProcessingDurationByParallelism	Duration breakdown for image analyses

Processing Duration by Parallelism

Path: tenant_report.processingDurations.byModelTypeAndParallelism.image

Field	Type	Description
single	float | null	Average duration in minutes for single processing mode. Can be null if no single analyses occurred during the reporting period.
bulk	float | null	Average duration in minutes for bulk processing mode. Can be null if no bulk analyses occurred during the reporting period.