cloudflare/src/resources/organizations/billing/usage.ts

The official TypeScript library for the Cloudflare API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../../core/resource';
import { APIPromise } from '../../../core/api-promise';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

export class BaseUsage extends APIResource {
  static override readonly _key: readonly ['organizations', 'billing', 'usage'] = Object.freeze([
    'organizations',
    'billing',
    'usage',
  ] as const);

  /**
   * Returns cost and usage data for all accounts within an organization, aligned
   * with the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/)
   * Cost and Usage dataset specification.
   *
   * Each record represents one billable metric for one account on one day. This
   * includes all metered usage, including usage that falls within free-tier
   * allowances and may result in zero cost. The response includes usage for every
   * account belonging to the specified organization.
   *
   * **Note:** Cost and pricing fields are not yet populated and will be absent from
   * responses until billing integration is complete.
   *
   * When `from` and `to` are omitted, defaults to the start of the current month
   * through today. The maximum date range is 31 days.
   *
   * An organization with no accounts, or an organization ID that does not exist,
   * returns a successful response with an empty result set rather than an error.
   */
  get(
    organizationID: string,
    query: UsageGetParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<UsageGetResponse> {
    return (
      this._client.get(path`/organizations/${organizationID}/billable/usage`, {
        query,
        ...options,
      }) as APIPromise<{ result: UsageGetResponse }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Usage extends BaseUsage {}

/**
 * Contains the array of cost and usage records.
 */
export type UsageGetResponse = Array<UsageGetResponse.UsageGetResponseItem>;

export namespace UsageGetResponse {
  /**
   * A single cost and usage record for a metered product within a specific charge
   * period, aligned with the FinOps FOCUS v1.3 specification.
   */
  export interface UsageGetResponseItem {
    /**
     * Highest-level classification of a charge based on the nature of how it gets
     * billed. Currently only "Usage" is supported.
     */
    ChargeCategory: 'Usage';

    /**
     * Self-contained summary of the charge's purpose and price.
     */
    ChargeDescription: string;

    /**
     * Indicates how often a charge occurs. Currently only "Usage-Based" is supported.
     */
    ChargeFrequency: 'Usage-Based';

    /**
     * Exclusive end of the time interval during which the usage was consumed.
     */
    ChargePeriodEnd: string;

    /**
     * Inclusive start of the time interval during which the usage was consumed.
     */
    ChargePeriodStart: string;

    /**
     * Measured usage amount within the charge period. Reflects raw metered consumption
     * before pricing transformations.
     */
    ConsumedQuantity: number;

    /**
     * Unit of measure for the consumed quantity (e.g., "GB", "Requests",
     * "vCPU-Hours").
     */
    ConsumedUnit: string;

    /**
     * Name of the entity providing the underlying infrastructure or platform.
     */
    HostProviderName: string;

    /**
     * Name of the entity responsible for invoicing for the services consumed.
     */
    InvoiceIssuerName: string;

    /**
     * Name of the entity that made the services available for purchase.
     */
    ServiceProviderName: string;

    /**
     * The unique identifier for the billable metric in the Cloudflare catalog.
     * Cloudflare extension; replaces FOCUS SkuId.
     */
    x_BillableMetricId: string;

    /**
     * A charge serving as the basis for invoicing, inclusive of all reduced rates and
     * discounts while excluding the amortization of upfront charges (one-time or
     * recurring).
     */
    BilledCost?: number | null;

    /**
     * Public identifier of the Cloudflare account (account tag). Omitted when account
     * is not part of the requested grouping, and always omitted for usage measured at
     * contract level, even when grouping by account: that usage is returned as its own
     * record with no account.
     */
    BillingAccountId?: string;

    /**
     * Display name of the Cloudflare account. Omitted when account is not part of the
     * requested grouping, and for usage measured at contract level.
     */
    BillingAccountName?: string;

    /**
     * Currency that a charge was billed in (ISO 4217).
     */
    BillingCurrency?: string | null;

    /**
     * Exclusive end of the billing cycle that contains this usage record.
     */
    BillingPeriodEnd?: string | null;

    /**
     * Inclusive start of the billing cycle that contains this usage record.
     */
    BillingPeriodStart?: string | null;

    /**
     * Indicates whether the row represents a correction to one or more charges
     * invoiced in a previous billing period.
     */
    ChargeClass?: 'Correction' | null;

    /**
     * Cost calculated by multiplying ContractedUnitPrice and the corresponding
     * PricingQuantity.
     */
    ContractedCost?: number | null;

    /**
     * The agreed-upon unit price for a single PricingUnit of the associated billable
     * metric, inclusive of negotiated discounts, if present, while excluding any other
     * discounts.
     */
    ContractedUnitPrice?: number | null;

    /**
     * The amortized cost of the charge after applying all reduced rates, discounts,
     * and the applicable portion of relevant, prepaid purchases (one-time or
     * recurring) that covered the charge.
     */
    EffectiveCost?: number | null;

    /**
     * Cost calculated by multiplying ListUnitPrice and the corresponding
     * PricingQuantity.
     */
    ListCost?: number | null;

    /**
     * Suggested provider-published unit price for a single PricingUnit of the
     * associated billable metric, exclusive of any discounts.
     */
    ListUnitPrice?: number | null;

    /**
     * Volume of a given service used or purchased, based on the PricingUnit.
     */
    PricingQuantity?: number | null;

    /**
     * Provider-specified measurement unit for determining unit prices, indicating how
     * the provider rates measured usage after applying pricing rules like block
     * pricing.
     */
    PricingUnit?: string | null;

    /**
     * Provider-assigned identifier for an isolated geographic area where a service is
     * provided.
     */
    RegionId?: string | null;

    /**
     * Name of an isolated geographic area where a service is provided.
     */
    RegionName?: string | null;

    /**
     * Unique identifier assigned to a grouping of services. For Cloudflare, this is
     * the subscription or contract ID.
     */
    SubAccountId?: string;

    /**
     * Name assigned to a grouping of services. For Cloudflare, this is the
     * subscription or contract display name.
     */
    SubAccountName?: string;

    /**
     * Tag values for the requested `GroupBy` keys. Omitted when `GroupBy` is not
     * provided. Missing keys are omitted, and key-only tags are returned as boolean
     * `true`. All other tag values are strings.
     */
    Tags?: { [key: string]: string | true };

    /**
     * The display name of the billable metric. Cloudflare extension; replaces FOCUS
     * SkuMeter.
     */
    x_BillableMetricName?: string;

    /**
     * The product category the charge belongs to (e.g., "Developer", "Cloudflare
     * One"). Cloudflare extension; replaces FOCUS ServiceCategory.
     */
    x_ProductCategoryName?: string;

    /**
     * The unique identifier for the product family in the Cloudflare catalog.
     * Cloudflare extension; replaces FOCUS ServiceId.
     */
    x_ProductFamilyId?: string;

    /**
     * The product family the charge belongs to (e.g., "R2", "Workers"). Cloudflare
     * extension; replaces FOCUS ServiceName.
     */
    x_ProductFamilyName?: string;

    /**
     * The identifier for the Cloudflare zone (zone tag). Omitted when zone is not part
     * of the requested grouping, and always omitted for usage measured at contract
     * level, even when grouping by zone. Cloudflare extension.
     */
    x_ZoneId?: string | null;

    /**
     * The display name of the Cloudflare zone. Omitted when zone is not part of the
     * requested grouping, and for usage measured at contract level. Cloudflare
     * extension.
     */
    x_ZoneName?: string | null;
  }
}

export interface UsageGetParams {
  /**
   * Start date for the usage query (ISO 8601). Required if `to` is set. When omitted
   * along with `to`, defaults to the start of the current month. Filters by charge
   * period (when consumption happened), not billing period. The maximum date range
   * is 31 days.
   */
  from?: string;

  /**
   * End date for the usage query (ISO 8601). Required if `from` is set. When omitted
   * along with `from`, defaults to today. Filters by charge period (when consumption
   * happened), not billing period. The maximum date range is 31 days.
   */
  to?: string;
}

export declare namespace Usage {
  export { type UsageGetResponse as UsageGetResponse, type UsageGetParams as UsageGetParams };
}