{ "openapi": "3.1.2", "info": { "title": "Cloud Billing API", "description": "The Cloud Billing API enables you to retrieve cost and usage information.", "version": "1.0.0" }, "servers": [ { "url": "https://cloud.elastic.co", "description": "Public" } ], "paths": { "/api/v1/billing/organization/{organization_id}/budget": { "post": { "tags": [ "Billing Budgets" ], "summary": "Create a budget for the organization.", "description": "Create a new budget for an organization", "operationId": "createBudgetV1", "parameters": [ { "name": "organization_id", "in": "path", "description": "The organization ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "scope_type", "scope_values", "amount", "alerts" ], "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the budget is active", "default": true }, "alerts": { "type": "array", "items": { "required": [ "operator", "threshold" ], "type": "object", "properties": { "operator": { "enum": [ "gte" ], "type": "string", "description": "Alert operator" }, "threshold": { "type": "integer", "description": "Alert threshold value" }, "threshold_type": { "enum": [ "percentage" ], "type": "string", "description": "Type of alert threshold; only percentage is supported", "default": "percentage" } } }, "description": "List of budget alerts. The service enforces a server-side limit on the number of alerts per budget." }, "amount": { "type": "integer", "description": "Budget amount in ECU" }, "name": { "type": "string", "description": "Optional name for the budget" }, "period": { "enum": [ "monthly" ], "type": "string", "description": "Deprecated, use window instead. period=monthly is equivalent to a monthly window with reset_on.day=1. If both period and window are sent they must describe the same schedule.", "deprecated": true }, "recipient_group": { "type": "array", "items": { "enum": [ "organization-admins", "billing-admins", "resource-viewers", "resource-editors", "resource-admins" ], "type": "string" }, "description": "Optional list of recipient types who receive budget alerts (organization-admins, billing-admins, resource-viewers, resource-editors, resource-admins). resource-viewers, resource-editors and resource-admins cannot be used with scope_type=organization. organization-admins, billing-admins are included by default if recipient_group is not provided." }, "scope_type": { "enum": [ "organization", "cloud_resource" ], "type": "string", "description": "The scope type of the budget" }, "scope_values": { "type": "array", "items": { "type": "string" }, "description": "List of scope values" }, "window": { "required": [ "repeat_unit", "repeat_every" ], "type": "object", "properties": { "repeat_every": { "minimum": 1, "type": "integer", "description": "Number of units between resets" }, "repeat_unit": { "enum": [ "day", "week", "month", "year" ], "type": "string", "description": "Calendar unit between resets" }, "reset_on": { "$ref": "#/components/schemas/BudgetResetOn" } }, "description": "Recurring budget window. Allowed (repeat_unit, repeat_every) pairs and the reset_on fields each one requires: daily (day, 1) with no reset_on; weekly (week, 1) with reset_on.weekday; monthly (month, 1) with reset_on.day; quarterly (month, 3) with reset_on.month, resetting on the 1st; yearly (year, 1) with reset_on.month and reset_on.day. Any other combination, or a missing or extra reset_on field, returns 400. Windows reset at 00:00 UTC. Days 29-31 clamp to the last day of shorter months, recomputed every period (day 31 resets on Jan 31, Feb 28, Mar 31, Apr 30). The current window start is returned as window.start_date and cannot be set by the client.", "example": { "repeat_every": 1, "repeat_unit": "month", "reset_on": { "day": 31 } } } } } } }, "required": true }, "responses": { "200": { "description": "Budget created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The created budget ID" } } }, "example": { "id": 432433423 } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Not allowed to create this budget" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/billing/organization/{organization_id}/budget/{budget_id}": { "post": { "tags": [ "Billing Budgets" ], "summary": "Update a budget for the organization.", "description": "Update an organization's existing budget", "operationId": "updateBudgetV1", "parameters": [ { "name": "organization_id", "in": "path", "description": "The organization ID", "required": true, "schema": { "type": "string" } }, { "name": "budget_id", "in": "path", "description": "The budget ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "scope_type", "scope_values", "amount", "alerts" ], "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the budget is active", "default": true }, "alerts": { "type": "array", "items": { "required": [ "operator", "threshold" ], "type": "object", "properties": { "operator": { "enum": [ "gte" ], "type": "string", "description": "Alert operator" }, "threshold": { "type": "integer", "description": "Alert threshold value" }, "threshold_type": { "enum": [ "percentage" ], "type": "string", "description": "Type of alert threshold; only percentage is supported", "default": "percentage" } } }, "description": "List of budget alerts. The service enforces a server-side limit on the number of alerts per budget." }, "amount": { "type": "integer", "description": "Budget amount in ECU" }, "name": { "type": "string", "description": "Optional name for the budget" }, "period": { "enum": [ "monthly" ], "type": "string", "description": "Deprecated, use window instead. period=monthly is equivalent to a monthly window with reset_on.day=1. If both period and window are sent they must describe the same schedule.", "deprecated": true }, "recipient_group": { "type": "array", "items": { "enum": [ "organization-admins", "billing-admins", "resource-viewers", "resource-editors", "resource-admins" ], "type": "string" }, "description": "Optional list of recipient types who receive budget alerts (organization-admins, billing-admins, resource-viewers, resource-editors, resource-admins). resource-viewers, resource-editors and resource-admins cannot be used with scope_type=organization." }, "scope_type": { "enum": [ "organization", "cloud_resource" ], "type": "string", "description": "The scope type of the budget" }, "scope_values": { "type": "array", "items": { "type": "string" }, "description": "List of scope values" }, "window": { "required": [ "repeat_unit", "repeat_every" ], "type": "object", "properties": { "repeat_every": { "minimum": 1, "type": "integer", "description": "Number of units between resets" }, "repeat_unit": { "enum": [ "day", "week", "month", "year" ], "type": "string", "description": "Calendar unit between resets" }, "reset_on": { "$ref": "#/components/schemas/BudgetResetOn" } }, "description": "Recurring budget window. Allowed (repeat_unit, repeat_every) pairs and the reset_on fields each one requires: daily (day, 1) with no reset_on; weekly (week, 1) with reset_on.weekday; monthly (month, 1) with reset_on.day; quarterly (month, 3) with reset_on.month, resetting on the 1st; yearly (year, 1) with reset_on.month and reset_on.day. Any other combination, or a missing or extra reset_on field, returns 400. Windows reset at 00:00 UTC. Days 29-31 clamp to the last day of shorter months, recomputed every period (day 31 resets on Jan 31, Feb 28, Mar 31, Apr 30). The current window start is returned as window.start_date and cannot be set by the client.", "example": { "repeat_every": 1, "repeat_unit": "month", "reset_on": { "day": 31 } } } } } } }, "required": true }, "responses": { "204": { "description": "Budget updated successfully" }, "400": { "description": "Invalid request" }, "403": { "description": "Not allowed to update this budget" }, "404": { "description": "Budget not found" }, "500": { "description": "Internal Server Error" } } } }, "/api/v1/billing/organization/{organization_id}/budgets": { "get": { "tags": [ "Billing Budgets" ], "summary": "List budgets for the organization.", "description": "Retrieves budgets for the specified organization. Admins receive all budgets; non-admins receive only budgets scoped to cloud resources they can access.", "operationId": "listBudgetsV1", "parameters": [ { "name": "organization_id", "in": "path", "description": "The organization ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Budgets successfully retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } } } } }, "500": { "description": "Internal server error (error_getting_budgets, error_fetching_cloud_resources)" } } } }, "/api/v1/billing/organization/{organization_id}/budgets/{budget_id}": { "delete": { "tags": [ "Billing Budgets" ], "summary": "Delete a budget for the organization.", "description": "Deletes the budget for the specified organization. Admins may delete any budget. Non-admins may delete only cloud-resource-scoped budgets for which they have update access on all scoped resources.", "operationId": "deleteBudgetV1", "parameters": [ { "name": "organization_id", "in": "path", "description": "The organization ID", "required": true, "schema": { "type": "string" } }, { "name": "budget_id", "in": "path", "description": "The budget ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Budget successfully deleted" }, "403": { "description": "Not allowed to delete this budget" }, "404": { "description": "Budget not found" }, "500": { "description": "Internal server error" } } }, "get": { "tags": [ "Billing Budgets" ], "summary": "Get a budget for the organization.", "description": "Retrieves a budget for the specified organization. Admins receive any budget in the organization. Non-admins receive organization-scoped budgets with 403 Forbidden; cloud-resource-scoped budgets are returned only when all scope values are instances they can access, otherwise 403 Forbidden.", "operationId": "getBudgetV1", "parameters": [ { "name": "organization_id", "in": "path", "description": "The organization ID", "required": true, "schema": { "type": "string" } }, { "name": "budget_id", "in": "path", "description": "The budget ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Budget successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "403": { "description": "Not allowed to read this budget" }, "404": { "description": "Budget not found" }, "500": { "description": "Internal server error" } } } }, "/api/v1/billing/organization/{organization_id}/history": { "get": { "tags": [ "Billing Organization" ], "summary": "Get the billing history for the organization.", "description": "Retrieves the billing statement and invoice history for the organization, including statement periods, amounts, statuses, and PDF download links when available.", "operationId": "getHistoryV1", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful fetched billing history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "required": [ "number", "organization_id", "period_start_date", "period_end_date", "issue_date", "type", "status", "invoiced_amount_in_cents" ], "type": "object", "properties": { "external_invoice_pdf_download": { "type": "string" }, "invoice_pdf_download": { "type": "string" }, "invoiced_amount_in_cents": { "type": "integer" }, "issue_date": { "type": "string", "format": "date" }, "number": { "type": "integer" }, "organization_id": { "type": "string" }, "payment_metadata": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "external_invoice_id": { "type": "string" } } }, "period_end_date": { "type": "string", "format": "date" }, "period_start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "type": { "type": "string" } } } }, "statements": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "ecu_total": { "type": "integer" }, "external_invoice_pdf_download": { "type": "string", "description": "Presigned S3 URL for the externally generated (e.g. Recurly) invoice PDF. Present only when that PDF exists in S3.\n" }, "invoiced_amount_in_cents": { "type": "integer" }, "issue_date": { "type": "string" }, "number": { "type": "string" }, "organization_id": { "type": "string" }, "payment_metadata": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "external_invoice_id": { "type": "string" } }, "description": "Present only when payment details exist (e.g. Recurly details for direct monthly CC statements).\n" }, "payment_method": { "enum": [ "CC", "PO" ], "type": "string", "description": "Payment method for the statement organization (\"CC\" or \"PO\").\n" }, "period_end_date": { "type": "string" }, "period_start_date": { "type": "string" }, "reseller": { "type": "boolean" }, "status": { "type": "string" }, "type": { "type": "string" }, "usage_pdf_download": { "type": "string" } } } } } }, "example": { "invoices": [ { "invoiced_amount_in_cents": 0, "issue_date": "2022-05-01", "number": 1, "organization_id": "1", "period_end_date": "2022-05-31", "period_start_date": "2022-05-01", "status": "paid", "type": "invoice" } ], "statements": [ ] } } } }, "401": { "description": "Access token is missing or invalid", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Not found." }, "500": { "description": "Internal Server Error." } } } }, "/api/v2/billing/organizations/{organization_id}/charts": { "get": { "tags": [ "Billing Charts" ], "summary": "Get the usage charts for the organization.", "description": "Retrieves the usage charts for the organization.\nAdmin callers receive all instances; non-admin user callers receive\ndata filtered to the instances they have access to (empty buckets if\nnone).\n", "operationId": "getChartsV2", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "A datetime for the beginning of the desired range. Non-UTC offsets are converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, the request is rejected.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "to", "in": "query", "description": "A datetime for the end of the desired range. Non-UTC offsets are converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, the request is rejected.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "bucketing_strategy", "in": "query", "description": "The desired bucketing strategy for the charts.", "schema": { "enum": [ "daily", "monthly" ], "type": "string" } } ], "responses": { "200": { "description": "Successfully return the usage charts of an organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Axis X position.", "format": "int64" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of chart item value." }, "name": { "type": "string", "description": "The name of the chart item value." }, "type": { "type": "string", "description": "Item type." }, "value": { "type": "number", "description": "The actual value of the chart item value.", "format": "double" } } }, "description": "The collection of values to plot the chart item." } } }, "description": "The list of chart item." } } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Not found." }, "424": { "description": "Failed dependency." }, "500": { "description": "Internal Server Error." } } } }, "/api/v2/billing/organizations/{organization_id}/costs/instances": { "get": { "tags": [ "Billing Costs Analysis" ], "summary": "Get instances costs for the organization.", "description": "Retrieves costs associated with all instances for the organization.\nAdmin callers receive all instances; non-admin user callers receive\ndata filtered to the instances they have access to (empty result if\nnone).\n", "operationId": "getCostsByInstancesV2", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier for the organization", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "A datetime for the beginning of the desired range. Any timezone offset is accepted and converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, UTC is assumed.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "to", "in": "query", "description": "A datetime for the end of the desired range. Any timezone offset is accepted and converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, UTC is assumed.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "include_names", "in": "query", "description": "Specifies whether to include project names in the result by querying the control plane", "schema": { "type": "boolean" } }, { "name": "Accept", "in": "header", "description": "Determines the response body format. Can be either application/json or text/csv.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The costs associated to a set of instances.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instances" } } } }, "400": { "description": "The specified data range is invalid." }, "403": { "description": "Current user does not have access to the requested organization." }, "404": { "description": "Organization not found." }, "500": { "description": "Internal server error." } } } }, "/api/v2/billing/organizations/{organization_id}/costs/instances/{instance_id}/items": { "get": { "tags": [ "Billing Costs Analysis" ], "summary": "Get itemized costs by instance for the organization.", "description": "Retrieves the costs associated to a set of items billed for a single instance.\nAdmin callers receive the data unconditionally; non-admin user callers\nreceive 403 if the instance is not in their accessible cloud resources.\n", "operationId": "getItemizedCostsByInstanceV2", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier for the organization", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "description": "Identifier for the instance", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "A datetime for the beginning of the desired range. Any timezone offset is accepted and converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, UTC is assumed.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "to", "in": "query", "description": "A datetime for the end of the desired range. Any timezone offset is accepted and converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, UTC is assumed.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "Accept", "in": "header", "description": "Determines the response body format. Can be either application/json or text/csv.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The costs associated to a set of items billed for a single instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "400": { "description": "The specified data range is invalid." }, "403": { "description": "Current user does not have access to the requested organization,\nor (for non-admin callers) does not have access to the requested\ninstance.\n" }, "404": { "description": "Organization not found." }, "500": { "description": "Internal server error." } } } }, "/api/v2/billing/organizations/{organization_id}/costs/items": { "get": { "tags": [ "Billing Costs Analysis" ], "summary": "Get itemized costs for the organization.", "description": "Retrieves costs associated with all items for the organization.\nAdmin callers receive all items; non-admin user callers are\nfiltered to items billed against instances they have access to.\n", "operationId": "getCostsByItemsV2", "parameters": [ { "name": "organization_id", "in": "path", "description": "Identifier for the organization", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "A datetime for the beginning of the desired range. Any timezone offset is accepted and converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, UTC is assumed.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "to", "in": "query", "description": "A datetime for the end of the desired range. Any timezone offset is accepted and converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, UTC is assumed.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "serverless_group_by", "in": "query", "description": "How to group the serverless items.", "schema": { "enum": [ "product", "product_family" ], "type": "string" } }, { "name": "Accept", "in": "header", "description": "Determines the response body format. Can be either application/json or text/csv.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The costs associated to a set of items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "400": { "description": "The specified data range is invalid." }, "403": { "description": "Current user does not have access to the requested organization." }, "404": { "description": "Organization not found." }, "500": { "description": "Internal server error." } } } }, "/api/v2/billing/organizations/{organization_id}/instances/{instance_id}/charts": { "get": { "tags": [ "Billing Charts" ], "summary": "Get the usage charts for the instance of an organization.", "description": "Retrieves the usage charts for the organization's instance.\nAdmin callers receive the data unconditionally; non-admin user callers\nreceive 403 if the instance is not in their accessible cloud resources.\n", "operationId": "getChartsByInstanceV2", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "A datetime for the beginning of the desired range. Non-UTC offsets are converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, the request is rejected.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "to", "in": "query", "description": "A datetime for the end of the desired range. Non-UTC offsets are converted to UTC internally. Responses always contain UTC values. If no timezone offset is specified, the request is rejected.", "required": true, "schema": { "type": "string" }, "example": "2021-04-21T00:00:00+00:00" }, { "name": "bucketing_strategy", "in": "query", "description": "The desired bucketing strategy for the charts.", "schema": { "enum": [ "daily", "monthly" ], "type": "string" } }, { "name": "instance_type", "in": "query", "description": "The type of the instances to be returned.", "schema": { "enum": [ "all", "deployments", "projects" ], "type": "string" } } ], "responses": { "200": { "description": "Successfully return the usage charts of an organization's instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Axis X position.", "format": "int64" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of chart item value." }, "name": { "type": "string", "description": "The name of the chart item value." }, "type": { "type": "string", "description": "Item type." }, "value": { "type": "number", "description": "The actual value of the chart item value.", "format": "double" } } }, "description": "The collection of values to plot the chart item." } } }, "description": "The list of chart item." } } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Caller does not have access to the requested instance." }, "404": { "description": "Not found." }, "424": { "description": "Failed dependency." }, "500": { "description": "Internal Server Error." } } } } }, "components": { "schemas": { "Budget": { "required": [ "id", "scope_type", "scope_values", "amount", "period", "active", "alerts", "recipient_group" ], "type": "object", "properties": { "active": { "type": "boolean" }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/BudgetAlert" } }, "amount": { "type": "integer" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "period": { "enum": [ "monthly" ], "type": "string", "x-enum-name": "Period", "x-module-name": "cloud.costs_alerting._types" }, "recipient_group": { "type": "array", "items": { "enum": [ "organization-admins", "billing-admins", "resource-viewers", "resource-editors", "resource-admins" ], "type": "string", "x-enum-name": "RecipientType", "x-module-name": "cloud.costs_alerting._types" } }, "scope_type": { "enum": [ "organization", "cloud_resource" ], "type": "string", "x-enum-name": "ScopeType", "x-module-name": "cloud.costs_alerting._types" }, "scope_values": { "type": "array", "items": { "type": "string" } }, "window": { "$ref": "#/components/schemas/BudgetWindow" } }, "description": "Budget(id: 'int', scope_type: '_types.ScopeType', scope_values: 'list[str]', amount: 'int', period: '_types.Period', name: 'str | None', active: 'bool', created_at: 'str | None', alerts: 'list[BudgetAlert]', recipient_group: 'list[_types.RecipientType]', window: 'BudgetWindow | None' = None)", "x-module-name": "cloud.billing_service.apps.budgets.api.schema" }, "BudgetAlert": { "required": [ "id", "operator", "threshold", "threshold_type" ], "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "integer" }, "last_exceeded_at": { "type": "string" }, "operator": { "enum": [ "gte" ], "type": "string", "x-enum-name": "Operator", "x-module-name": "cloud.costs_alerting._types" }, "threshold": { "type": "integer" }, "threshold_type": { "enum": [ "percentage" ], "type": "string", "x-enum-name": "ThresholdType", "x-module-name": "cloud.costs_alerting._types" } }, "description": "BudgetAlert(id: 'int', operator: '_types.Operator', threshold: 'int', threshold_type: '_types.ThresholdType', created_at: 'str | None', last_exceeded_at: 'str | None')", "x-module-name": "cloud.billing_service.apps.budgets.api.schema" }, "BudgetResetOn": { "type": "object", "properties": { "day": { "type": "integer", "description": "Day of the month, 1 to 31." }, "month": { "enum": [ "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec" ], "type": "string", "x-enum-name": "Month", "x-module-name": "cloud.costs_alerting._types" }, "weekday": { "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "type": "string", "x-enum-name": "Weekday", "x-module-name": "cloud.costs_alerting._types" } }, "description": "The user's reset selection. Only the fields required by the window frequency are set: weekly uses weekday, monthly uses day, quarterly uses month, yearly uses month and day. Days 29-31 clamp to the last day of shorter months, recomputed every period from this selection (day 31 resets on Jan 31, Feb 28, Mar 31, Apr 30; Feb 29 resets on Feb 28 in non-leap years).", "x-module-name": "cloud.billing_service.apps.budgets.api.schema" }, "BudgetWindow": { "required": [ "start_date", "repeat_unit", "repeat_every", "reset_on" ], "type": "object", "properties": { "repeat_every": { "type": "integer" }, "repeat_unit": { "enum": [ "day", "week", "month", "year" ], "type": "string", "x-enum-name": "RepeatUnit", "x-module-name": "cloud.costs_alerting._types" }, "reset_on": { "$ref": "#/components/schemas/BudgetResetOn" }, "start_date": { "type": "string", "description": "Read-only. Start of the current window as a UTC date (YYYY-MM-DD), computed by the server from reset_on.", "example": "2026-02-28" } }, "description": "Recurring budget window. Allowed (repeat_unit, repeat_every) pairs: daily (day, 1), weekly (week, 1), monthly (month, 1), quarterly (month, 3), yearly (year, 1). Windows reset at 00:00 UTC; spend is counted from the later of the window start and the budget creation time.", "x-module-name": "cloud.billing_service.apps.budgets.api.schema" }, "DisplayQuantity": { "required": [ "value", "formatted_value", "type" ], "type": "object", "properties": { "formatted_value": { "type": "string" }, "type": { "enum": [ "default", "normalized" ], "type": "string", "x-enum-name": "DisplayQuantityType", "x-module-name": "cloud.costs.v2" }, "value": { "type": [ "integer", "number" ] } }, "description": "Display quantity", "x-module-name": "cloud.costs.v2" }, "Instance": { "required": [ "id", "name", "total_ecu", "type", "product_line_items" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "product_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLineItem" } }, "total_ecu": { "type": "integer" }, "type": { "type": "string" } }, "description": "Instance(id: 'str', name: 'str', total_ecu: 'int', type: 'str', product_line_items: 'list[ProductLineItem]')", "x-module-name": "cloud.costs.v2" }, "Instances": { "required": [ "total_ecu", "instances" ], "type": "object", "properties": { "instances": { "type": "array", "items": { "$ref": "#/components/schemas/Instance" } }, "total_ecu": { "type": "integer" } }, "description": "Instances(total_ecu: 'int', instances: 'list[Instance]')", "x-module-name": "cloud.costs.v2" }, "Items": { "required": [ "total_ecu", "products" ], "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "total_ecu": { "type": "integer" } }, "description": "Items(total_ecu: 'int', products: 'list[Product]')", "x-module-name": "cloud.costs.v2" }, "Product": { "required": [ "total_ecu", "type", "product_line_items" ], "type": "object", "properties": { "product_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLineItem" } }, "total_ecu": { "type": "integer" }, "type": { "type": "string" } }, "description": "Product(total_ecu: 'int', type: 'str', product_line_items: 'list[ProductLineItem]')", "x-module-name": "cloud.costs.v2" }, "ProductLineItem": { "required": [ "name", "total_ecu", "type", "sku", "unit", "quantity", "display_quantity", "rate", "quantities" ], "type": "object", "properties": { "display_quantity": { "$ref": "#/components/schemas/DisplayQuantity" }, "kind": { "type": "string" }, "name": { "type": "string" }, "quantities": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLineItemQuantity" } }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "rate": { "$ref": "#/components/schemas/Rate" }, "sku": { "type": "string" }, "total_ecu": { "type": "integer" }, "type": { "type": "string" }, "unit": { "type": "string" } }, "description": "ProductLineItem(name: 'str', total_ecu: 'int', type: 'str', sku: 'str', unit: 'str', quantity: 'Quantity', display_quantity: 'DisplayQuantity', rate: 'Rate', kind: 'str | None', quantities: 'list[ProductLineItemQuantity]')", "x-module-name": "cloud.costs.v2" }, "ProductLineItemQuantity": { "required": [ "from", "to", "total_ecu", "rate", "tiers" ], "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "rate": { "$ref": "#/components/schemas/Rate" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLineItemTier" } }, "to": { "type": "string", "format": "date-time" }, "total_ecu": { "type": "integer" } }, "description": " Represents the cost structure, segmenting the quantities by price range and allocating the usage to tiers if price is tiered. If price is not tiered and if the pricing didn't change during the entire usage range, quantities will be empty (otherwise it would be redundant data). ", "x-module-name": "cloud.costs.v2" }, "ProductLineItemTier": { "required": [ "min", "total_ecu", "quantity", "rate" ], "type": "object", "properties": { "max": { "type": "integer" }, "min": { "type": "integer" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "rate": { "$ref": "#/components/schemas/Rate" }, "total_ecu": { "type": "integer" } }, "description": "ProductLineItemTier(min: 'int', max: 'int | None', total_ecu: 'int', quantity: 'Quantity', rate: 'Rate')", "x-module-name": "cloud.costs.v2" }, "Quantity": { "required": [ "value", "formatted_value" ], "type": "object", "properties": { "formatted_value": { "type": "string" }, "value": { "type": [ "integer", "number" ] } }, "description": "Quantity", "x-module-name": "cloud.costs.v2" }, "Rate": { "required": [ "value", "formatted_value" ], "type": "object", "properties": { "formatted_value": { "type": "string" }, "value": { "type": "integer" } }, "description": "Rate(value: 'int', formatted_value: 'str')", "x-module-name": "cloud.costs.v2" }, "UnauthorizedError": { "type": "string" } } }, "tags": [ { "name": "Billing Costs Analysis", "description": "The billing costs analysis API is used to manage the billing costs analysis details." }, { "name": "Billing Organization", "description": "The billing organization API is used to manage the billing organization details." }, { "name": "Billing Charts", "description": "The billing charts API is used to manage the billing charts details." }, { "name": "Billing Budgets", "description": "The billing budgets API is used to manage the billing budgets details." } ], "x-topics": [ { "title": "Authentication", "content": "Platform Billing Service API supports key-based authentication.\nYou must [create an API key](https://www.elastic.co/guide/en/cloud/current/ec-api-authentication.html) and use the encoded value in the request header.\nFor convenience, you can export your API key into your shell environment:\n\n```\nexport EC_API_KEY=\"YOUR_GENERATED_API_KEY\"\n```\n\nFor example, the following `curl` command retrieves costs associated with all items:\n\n```\ncurl -H \"Authorization: ApiKey $EC_API_KEY\" \"https://cloud.elastic.co/api/v2/billing/organizations/{organization_id}/costs/items?from=2025-08-01T00:00:00Z&to=2025-08-31T00:00:00Z\"\n```\n" } ] }