AuditAggregationQuery

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vertesiahq/json-schema/vertesiahq-audit-aggregation-query-schema.json",
  "title": "AuditAggregationQuery",
  "description": "Safe audit aggregation query. The server always applies the authenticated account scope and, for project-scoped principals, replaces projectId with the authenticated project.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vertesiahq-audit-trail-api-openapi.yml#/components/schemas/AuditAggregationQuery",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Optional account-admin project filter. Ignored for project-scoped principals."
    },
    "from": {
      "type": "string",
      "description": "Start time; defaults to 30 days before to. The server caps the range at 366 days."
    },
    "to": {
      "type": "string",
      "description": "End time; defaults to the current time."
    },
    "filter": {
      "$ref": "#/$defs/AuditAggregationFilter"
    },
    "groupBy": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AuditAggregationGroup"
      }
    },
    "metrics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AuditAggregationMetric"
      }
    },
    "limit": {
      "type": "number",
      "description": "Maximum groups returned (default 50, max 200)."
    }
  },
  "required": [
    "metrics"
  ],
  "additionalProperties": false,
  "$defs": {
    "AuditAction": {
      "anyOf": [
        {
          "$ref": "#/$defs/KnownAuditAction"
        },
        {
          "type": "string"
        }
      ]
    },
    "AuditAggregationDetailField": {
      "type": "string",
      "enum": [
        "pipeline",
        "verdict",
        "workflow_type",
        "rule_id"
      ]
    },
    "AuditAggregationDetailFilter": {
      "type": "object",
      "properties": {
        "field": {
          "$ref": "#/$defs/AuditAggregationDetailField"
        },
        "values": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "field",
        "values"
      ],
      "additionalProperties": false
    },
    "AuditAggregationDimension": {
      "type": "string",
      "enum": [
        "time",
        "action",
        "resource_type",
        "event_category",
        "provider",
        "project_id",
        "principal_id",
        "actor_id",
        "user_id",
        "details.pipeline",
        "details.verdict",
        "details.workflow_type",
        "details.rule_id",
        "model"
      ]
    },
    "AuditAggregationDistinctField": {
      "type": "string",
      "enum": [
        "resource_id",
        "request_id",
        "principal_id",
        "actor_id",
        "user_id"
      ]
    },
    "AuditAggregationFilter": {
      "type": "object",
      "properties": {
        "actions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AuditAction"
          }
        },
        "resourceTypes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "eventCategories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EventCategory"
          }
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "principalTypes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Restrict events to top-level actor categories such as user or apikey."
        },
        "success": {
          "type": "boolean"
        },
        "details": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AuditAggregationDetailFilter"
          }
        }
      },
      "additionalProperties": false
    },
    "AuditAggregationGroup": {
      "type": "object",
      "properties": {
        "dimension": {
          "$ref": "#/$defs/AuditAggregationDimension"
        },
        "resolution": {
          "$ref": "#/$defs/AuditAggregationResolution",
          "description": "Required for the time dimension; defaults to day."
        }
      },
      "required": [
        "dimension"
      ],
      "additionalProperties": false
    },
    "AuditAggregationMetric": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable key used in response rows. Must contain only letters, numbers, underscores, or hyphens."
        },
        "operation": {
          "$ref": "#/$defs/AuditAggregationOperation"
        },
        "field": {
          "$ref": "#/$defs/AuditAggregationDistinctField",
          "description": "Required for count_distinct."
        },
        "meterCategory": {
          "type": "string",
          "description": "Required for meter operations."
        },
        "meterType": {
          "type": "string",
          "description": "Required for meter operations."
        }
      },
      "required": [
        "id",
        "operation"
      ],
      "additionalProperties": false
    },
    "AuditAggregationOperation": {
      "type": "string",
      "enum": [
        "count",
        "count_distinct",
        "sum_meter",
        "average_meter"
      ]
    },
    "AuditAggregationResolution": {
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month"
      ]
    },
    "EventCategory": {
      "type": "string",
      "enum": [
        "content",
        "workflow",
        "security",
        "billing",
        "system",
        "external"
      ]
    },
    "KnownAuditAction": {
      "type": "string",
      "enum": [
        "create",
        "update",
        "delete",
        "bulk_create",
        "bulk_change_type",
        "bulk_update",
        "bulk_delete",
        "attach",
        "detach",
        "credentials_fill",
        "credentials_totp_generation",
        "publish",
        "unpublish",
        "search",
        "read",
        "inference",
        "embedding",
        "image_generation",
        "document_processed"
      ]
    }
  }
}