metering.proto

syntax = "proto3";

package qdrant.cloud.metering.v1;

import "buf/validate/validate.proto";
import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "qdrant/cloud/common/v1/common.proto";

// MeteringService is the API to retrieve usage data used for billing purposes.
service MeteringService {
  // The API version of this service.
  option (qdrant.cloud.common.v1.api_version) = {
    major: 1
    minor: 0
    patch: 0
  };
  // Lists aggregated monthly meterings for the account identified by the given ID.
  // Each summary represents the total metering amount for one month.
  // Required permissions:
  // - read:payment_information
  rpc ListMonthlyMeterings(ListMonthlyMeteringsRequest) returns (ListMonthlyMeteringsResponse) {
    // permissions
    option (common.v1.permissions) = "read:payment_information";
    // gRPC Gateway REST call
    option (google.api.http) = {get: "/api/metering/v1/accounts/{account_id}/meterings"};
  }
  // Lists detailed metering entries for a specific month for the account identified by the given ID.
  // Required permissions:
  // - read:payment_information
  rpc ListMeterings(ListMeteringsRequest) returns (ListMeteringsResponse) {
    // permissions
    option (common.v1.permissions) = "read:payment_information";
    // gRPC Gateway REST call
    option (google.api.http) = {get: "/api/metering/v1/accounts/{account_id}/meterings/{year}/{month}"};
  }
  // Returns the usage breakdown for the account identified by the given ID, within the requested time range.
  // For parent billing accounts, the response aggregates usage across all child accounts.
  // Required permissions:
  // - read:payment_information
  rpc GetUsageBreakdown(GetUsageBreakdownRequest) returns (GetUsageBreakdownResponse) {
    // permissions
    option (common.v1.permissions) = "read:payment_information";
    // gRPC Gateway REST call
    option (google.api.http) = {get: "/api/metering/v1/accounts/{account_id}/usage-breakdown"};
  }
}

// ListMonthlyMeteringsRequest is the request for the ListMonthlyMeterings function
message ListMonthlyMeteringsRequest {
  // The identifier of the account (in GUID format).
  // This is a required field.
  string account_id = 1 [(buf.validate.field).string = {uuid: true}];
}

// ListMonthlyMeterings is the response from the ListMonthlyMeterings function
message ListMonthlyMeteringsResponse {
  // List of monthly metering summaries.
  repeated MonthlyMeteringSummary items = 1;
}

// ListMeteringsRequest is the request for the ListMeterings function
message ListMeteringsRequest {
  // The identifier of the account (in GUID format).
  // This is a required field.
  string account_id = 1 [(buf.validate.field).string = {uuid: true}];
  // The year to filter meterings by (e.g., 2025).
  int32 year = 2 [(buf.validate.field).int32 = {
    gte: 2000
    lte: 3000
  }];
  // The month to filter meterings by (1 = January, 12 = December).
  int32 month = 3 [(buf.validate.field).int32 = {
    gte: 1
    lte: 12
  }];
}

// ListMeteringsResponse is the response from the ListMeterings function
message ListMeteringsResponse {
  // List of detailed metering items for the specified month.
  repeated MeteringItem items = 1;
}

// MonthlyMeteringSummary represents a single month's metering summary.
message MonthlyMeteringSummary {
  // The year this summary represents (e.g., 2025).
  int32 year = 1 [(buf.validate.field).int32 = {
    gte: 2000
    lte: 3000
  }];
  // The month this summary represents (1 = January, 12 = December).
  int32 month = 2 [(buf.validate.field).int32 = {
    gte: 1
    lte: 12
  }];
  // Total amount for the month in millicents.
  // Example: 499900 = $4.999
  int64 amount_millicents = 3 [(buf.validate.field).int64.gte = 0];
  // Currency of the amount, in ISO 4217 format (e.g., "USD").
  string currency = 4 [(buf.validate.field).string = {
    len: 3
    pattern: "^[A-Z]{3}$"
  }];
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// Metering represents a detailed metering item.
message MeteringItem {
  // The identifier of the account this metering item belongs to (in GUID format).
  string account_id = 1 [(buf.validate.field).string = {uuid: true}];
  // The identifier of the cluster associated with this usage (in GUID format).
  string cluster_id = 2 [(buf.validate.field).string = {uuid: true}];
  // The name of the cluster involved in this metering.
  string cluster_name = 3 [(buf.validate.field).string.min_len = 1];
  // The start time of the metering window (UTC).
  google.protobuf.Timestamp start_time = 4 [(buf.validate.field).required = true];
  // The end time of the metering window (UTC).
  google.protobuf.Timestamp end_time = 5 [(buf.validate.field).required = true];
  option (buf.validate.message).cel = {
    id: "metering_item.end_time_gt_start_time"
    message: "end_time must be after start_time"
    expression: "this.end_time > this.start_time"
  };
  // The identifier of the billable entity (in GUID format), such as a cluster
  // booking or another billable resource.
  string billable_entity_id = 6 [(buf.validate.field).string = {uuid: true}];
  // A reference name of the billable entity (e.g. "sentence-transformers/all-minilm-l6-v2", "my-cluster-foobar").
  optional string billable_entity_reference_name = 14 [(buf.validate.field).string.min_len = 1];
  // The type of the billable entity  (e.g., "cluster_booking", "resource_option", "backup", "inference_model").
  string billable_entity_type = 7 [(buf.validate.field).string.min_len = 1];
  // The unit price in millicents per hour (e.g., 4112 = $0.04112/hour).
  int32 price_per_hour = 8 [(buf.validate.field).int32.gte = 0];
  // Usage duration in decimal hours. (e.g., 2.5 = 2 hours and 30 minutes).
  double usage_hours = 9 [(buf.validate.field).double.gte = 0];
  // The total charge for this item, in millicents.
  int64 amount_millicents = 10 [(buf.validate.field).int64.gte = 0];
  // The total discount applied to this item, in millicents.
  optional int64 discount_amount_millicents = 11 [(buf.validate.field).int64.gte = 0];
  // The Discount applied as a percentage (e.g., 12.5).
  optional double discount_amount_percent = 12 [(buf.validate.field).double = {
    gte: 0
    lte: 100
  }];
  // Currency of the different amount values, in ISO 4217 format (e.g., "USD").
  string currency = 13 [(buf.validate.field).string = {
    len: 3
    pattern: "^[A-Z]{3}$"
  }];
  // Labels associated with the cluster at the time of metering.
  map<string, string> cluster_labels = 15;
}

// GetUsageBreakdownRequest is the request for the GetUsageBreakdown function
message GetUsageBreakdownRequest {
  // The identifier of the account (in GUID format).
  // This is a required field.
  string account_id = 1 [(buf.validate.field).string = {uuid: true}];
  // The inclusive start of the time range to return usage for.
  google.protobuf.Timestamp start_time = 2 [(buf.validate.field).required = true];
  // The exclusive end of the time range to return usage for. Must be after start_time.
  google.protobuf.Timestamp end_time = 3 [(buf.validate.field).required = true];
  option (buf.validate.message).cel = {
    id: "get_usage_breakdown_request.end_time_gt_start_time"
    message: "end_time must be after start_time"
    expression: "this.end_time > this.start_time"
  };
}

// GetUsageBreakdownResponse is the response from the GetUsageBreakdown function
message GetUsageBreakdownResponse {
  // The list of months that had usage in the requested time range.
  repeated UsageBreakdownMonth items = 1;
}

// UsageBreakdownMonth groups usage for a single calendar month.
message UsageBreakdownMonth {
  // The year this entry represents (e.g., 2025).
  int32 year = 1 [(buf.validate.field).int32 = {
    gte: 2000
    lte: 3000
  }];
  // The month this entry represents (1 = January, 12 = December).
  int32 month = 2 [(buf.validate.field).int32 = {
    gte: 1
    lte: 12
  }];
  // The accounts that had usage in this month.
  repeated UsageBreakdownAccount accounts = 3;
  // How this period's usage was paid for. Absent when the server did not resolve it.
  UsageBreakdownFunding funding = 4;
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// UsageBreakdownFunding states how much of a period's usage prepaid credits paid for.
message UsageBreakdownFunding {
  // The credits drawn in this period, per contract. Empty means all pay-as-you-go.
  repeated CreditDrawdown credits_drawn = 1;
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// CreditDrawdown is the amount one credit contract paid towards a usage period.
message CreditDrawdown {
  // The identifier of the credit contract.
  string credit_contract_id = 1 [(buf.validate.field).string.min_len = 1];
  // The amount drawn from it, in millicents.
  int64 amount_millicents = 2 [(buf.validate.field).int64.gte = 0];
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// UsageBreakdownAccount groups per-cluster usage for a single account in a given month.
message UsageBreakdownAccount {
  // The identifier of the account (in GUID format).
  string account_id = 1 [(buf.validate.field).string = {uuid: true}];
  // The display name of the account.
  string account_name = 2 [(buf.validate.field).string.min_len = 1];
  // The clusters that had usage in this month for this account.
  repeated UsageBreakdownCluster clusters = 3;
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// ClusterUsageConfig describes the shape and placement of a cluster
// for the cluster-usage billable metric.
message ClusterUsageConfig {
  // Cloud provider (e.g., "aws", "gcp", "azure", "hybrid").
  string cloud_provider = 1;
  // Cloud provider region (e.g., "eu-central-1").
  string region = 2;
  // Number of vCPUs per node.
  int32 cpu_vcpu = 3 [(buf.validate.field).int32.gte = 0];
  // Amount of RAM per node, in GiB.
  int32 ram_gib = 4 [(buf.validate.field).int32.gte = 0];
  // Disk size per node, in GiB.
  int32 disk_gib = 5 [(buf.validate.field).int32.gte = 0];
  // Whether the cluster is configured for multi-AZ.
  bool multi_az = 6;
  // Whether the cluster has GPU enabled.
  bool gpu_enabled = 7;
  // Pricing tier the cluster was billed under (e.g., "standard", "premium").
  string pricing_tier = 8;
  // Number of nodes in the cluster's active booking at the time of metering.
  int32 node_count = 9 [(buf.validate.field).int32.gte = 0];
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// ClusterExtraDiskConfig describes placement and tier for the
// cluster-extra-disk billable metric.
message ClusterExtraDiskConfig {
  // Cloud provider (e.g., "aws", "gcp", "azure", "hybrid").
  string cloud_provider = 1;
  // Cloud provider region (e.g., "eu-central-1").
  string region = 2;
  // Pricing tier the cluster was billed under (e.g., "standard", "premium").
  string pricing_tier = 3;
  // Extra disk attached to the cluster's active booking at the time of metering, in GiB.
  int32 extra_disk_gib = 4 [(buf.validate.field).int32.gte = 0];
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// ClusterStorageTierConfig describes placement and storage tier for
// the cluster-storage-tier billable metric.
message ClusterStorageTierConfig {
  // Cloud provider (e.g., "aws", "gcp", "azure", "hybrid").
  string cloud_provider = 1;
  // Cloud provider region (e.g., "eu-central-1").
  string region = 2;
  // Storage tier (e.g., "performance", "balanced").
  string storage_tier = 3;
  // Pricing tier the cluster was billed under (e.g., "standard", "premium").
  string pricing_tier = 4;
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// BackupStorageConfig describes placement and tier for the
// backup-storage billable metric.
message BackupStorageConfig {
  // Cloud provider (e.g., "aws", "gcp", "azure", "hybrid").
  string cloud_provider = 1;
  // Cloud provider region (e.g., "eu-central-1").
  string region = 2;
  // Pricing tier the cluster was billed under (e.g., "standard", "premium").
  string pricing_tier = 3;
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// InferenceConfig describes placement, model and tier for the
// inference-tokens billable metric.
message InferenceConfig {
  // Cloud provider (e.g., "aws", "gcp", "azure", "hybrid").
  string cloud_provider = 1;
  // Cloud provider region (e.g., "eu-central-1").
  string region = 2;
  // Model identifier (e.g., "qdrant/text-embedder-v1").
  string model_name = 3;
  // Pricing tier the cluster was billed under (e.g., "standard", "premium").
  string pricing_tier = 4;
}

// buf:lint:ignore QDRANT_CLOUD_REQUIRED_ENTITY_FIELDS
// UsageBreakdownCluster represents the usage for a single cluster within a month.
message UsageBreakdownCluster {
  // The identifier of the cluster (in GUID format).
  string cluster_id = 1 [(buf.validate.field).string = {uuid: true}];
  // The name of the cluster.
  string cluster_name = 2 [(buf.validate.field).string.min_len = 1];
  // Labels associated with the cluster at the time of metering.
  map<string, string> cluster_labels = 3;
  // The label key designated as the cluster's cost allocation label, if set.
  // Always one of the keys in cluster_labels.
  optional string cost_allocation_label = 17;
  // The start time of the metering window (UTC).
  google.protobuf.Timestamp start_time = 4 [(buf.validate.field).required = true];
  // The end time of the metering window (UTC).
  google.protobuf.Timestamp end_time = 5 [(buf.validate.field).required = true];
  // The total charge for this entry, in millicents.
  int64 amount_millicents = 6 [(buf.validate.field).int64.gte = 0];
  // Currency of the amount, in ISO 4217 format (e.g., "USD").
  string currency = 7 [(buf.validate.field).string = {
    len: 3
    pattern: "^[A-Z]{3}$"
  }];
  // The type of the billable entity (e.g., "cluster_booking", "backup", "inference_model").
  string billable_entity_type = 8 [(buf.validate.field).string.min_len = 1];
  // Per-metric configuration of the entity at the time of metering. Exactly
  // one variant is set, matching the billable entity type.
  oneof config {
    // Set when billable_entity_type is "Cluster".
    ClusterUsageConfig cluster_usage_config = 9;
    // Set when billable_entity_type is "Cluster Extra Disk".
    ClusterExtraDiskConfig cluster_extra_disk_config = 10;
    // Set when billable_entity_type is "Cluster Storage Tier".
    ClusterStorageTierConfig cluster_storage_tier_config = 11;
    // Set when billable_entity_type is "Backup".
    BackupStorageConfig backup_storage_config = 12;
    // Set when billable_entity_type is "Inference Tokens".
    InferenceConfig inference_config = 13;
  }
  // Quantity of the metric consumed during the period (cluster-wide,
  // integrated over the period). Per-metric meaning:
  //   - Cluster: node-hours
  //   - Cluster Extra Disk: GiB-hours
  //   - Cluster Storage Tier: node-hours
  //   - Backup: GiB-hours
  //   - Inference Tokens: tokens
  double quantity = 14 [(buf.validate.field).double.gte = 0];
  // The total discount applied to this entry, in millicents.
  // Net charge = amount_millicents - discount_amount_millicents.
  optional int64 discount_amount_millicents = 15 [(buf.validate.field).int64.gte = 0];
  // The discount applied as a percentage (e.g., 12.5).
  optional double discount_amount_percent = 16 [(buf.validate.field).double = {
    gte: 0
    lte: 100
  }];
  option (buf.validate.message).cel = {
    id: "usage_breakdown_cluster.end_time_gt_start_time"
    message: "end_time must be after start_time"
    expression: "this.end_time > this.start_time"
  };
}