Skip to content

Cost Explorer

All operations require authentication.

5 operationsv2/finops/costExplorer
View as Markdown (opens in a new tab)
Agent setup

Start the computation of a cost breakdownBeta

POST
/v2/finops/costExplorer/breakdown

Starts the asynchronous computation of the cost of the account over a range, split into periods of the granularity and into series of the groupBy dimension.

The amount of a period is the cost recognized during that period: the cost that first appears in the billing data during the period, not the cost of the usage of the period.

The granularity is the finest one used: when the range holds more than 744 periods of this width, the computation uses a coarser one, and the result gives the one used.

Read the progress and the result with GET /v2/finops/costExplorer/breakdown/{breakdownId}.

Returns 400 when:

  • from is not before to;
  • two filters name the same dimension;
  • groupBy or a filter names a dimension that GET /v2/finops/costExplorer/dimension does not list.

Returns 400 with the class Client::BadRequest::FeatureUnavailable when the account is not enrolled in the Cost Explorer.

Returns 400 with the class Client::BadRequest::DataUnavailable when the Cost Explorer has no data of the account before the end of the range.

Request body (required)

currency
CurrencyEnum

Currency to keep, for example EUR: only the cost lines billed in this currency are kept. Needed only when the cost lines of the range hold a non-zero cost in more than one currency. Null keeps every currency. The computation then ends in ERROR when more than one currency is present, and the error message lists them.

ValuesAUDCADCZKEURGBPINRLTLMADPLNPOINTSSGDTNDUSDXOF
filters
BreakdownFilter[]

Filters on the cost lines. A cost line is kept when it passes every filter, and a dimension without a filter keeps every value. Null or empty keeps every cost line.

from
required
stringdate-time

Start of the range, included

granularity
required
GranularityEnum

Finest width of a period. The computation uses a coarser one when the range holds more than 744 periods of this width.

ValuesDAYHOURMONTH
groupBy
string

Key of the dimension whose values split the cost into series, as GET /v2/finops/costExplorer/dimension lists it. Null groups by CATEGORY.

to
required
stringdate-time

End of the range, excluded. It must be after from.

Response

200BreakdownTasksuccessful operation
createdAt
read-only
stringdate-time

Date when the computation was started

errors
read-only
TaskError[]

Errors that ended the computation. Empty unless the status is ERROR.

id
read-only
stringuuid

Unique identifier of the computation

result
read-only
BreakdownResult

Cost breakdown. Null unless the status is DONE.

status
read-only
TaskStatusEnum

Status of the computation: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.

ValuesDONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUT
400objectError 400 response

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/finops/costExplorer/breakdown \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "errors": [ { "class": "string", "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "result": { "currency": "AUD", "from": "2024-01-01T12:00:00Z", "granularity": "DAY", "periods": [ { "amounts": { "key": 0 }, "end": "2024-01-01T12:00:00Z", "start": "2024-01-01T12:00:00Z" } ], "series": [ "string" ], "timezone": "UTC", "to": "2024-01-01T12:00:00Z", "totals": { "key": 0 }, "truncated": true }, "status": "DONE"}

Get a cost breakdown computation and its resultBeta

GET
/v2/finops/costExplorer/breakdown/{breakdownId}

Returns the status of a computation started with POST /v2/finops/costExplorer/breakdown. Poll this route until the status is DONE or ERROR. The result is set when the status is DONE.

Returns 404 when:

  • the account has no computation with this identifier;
  • the computation has expired.

Path parameters

breakdownId
required
stringuuid

Breakdown ID

Response

200BreakdownTasksuccessful operation
createdAt
read-only
stringdate-time

Date when the computation was started

errors
read-only
TaskError[]

Errors that ended the computation. Empty unless the status is ERROR.

id
read-only
stringuuid

Unique identifier of the computation

result
read-only
BreakdownResult

Cost breakdown. Null unless the status is DONE.

status
read-only
TaskStatusEnum

Status of the computation: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.

ValuesDONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUT

Example uses breakdownId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/finops/costExplorer/breakdown/{breakdownId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "errors": [ { "class": "string", "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "result": { "currency": "AUD", "from": "2024-01-01T12:00:00Z", "granularity": "DAY", "periods": [ { "amounts": { "key": 0 }, "end": "2024-01-01T12:00:00Z", "start": "2024-01-01T12:00:00Z" } ], "series": [ "string" ], "timezone": "UTC", "to": "2024-01-01T12:00:00Z", "totals": { "key": 0 }, "truncated": true }, "status": "DONE"}

List the dimensions that a cost breakdown can filter on or group byBeta

GET
/v2/finops/costExplorer/dimension

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200Dimension[]successful operation
key
read-only
string

Identifier of the dimension, for example CATEGORY, as the groupBy and the filters of a cost breakdown take it

label
read-only
string

Display name of the dimension, in English, for example Product category

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/finops/costExplorer/dimension \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "key": "string", "label": "string" }]

Start the listing of the values of every dimension in the cost lines of a rangeBeta

POST
/v2/finops/costExplorer/dimensionValue

Starts the asynchronous listing of the distinct values of every dimension that appear in the cost lines of the range. Each value can feed the matching filter of POST /v2/finops/costExplorer/breakdown.

Read the progress and the result with GET /v2/finops/costExplorer/dimensionValue/{dimensionValueId}.

Returns 400 when from is not before to.

Returns 400 with the class Client::BadRequest::FeatureUnavailable when the account is not enrolled in the Cost Explorer.

Returns 400 with the class Client::BadRequest::DataUnavailable when the Cost Explorer has no data of the account before the end of the range.

Request body (required)

from
required
stringdate-time

Start of the range, included

to
required
stringdate-time

End of the range, excluded. It must be after from.

Response

200DimensionValueTasksuccessful operation
createdAt
read-only
stringdate-time

Date when the listing was started

errors
read-only
TaskError[]

Errors that ended the listing. Empty unless the status is ERROR.

id
read-only
stringuuid

Unique identifier of the listing

result
read-only
DimensionValueList[]

Values of each dimension, in the order of GET /v2/finops/costExplorer/dimension. Null unless the status is DONE.

status
read-only
TaskStatusEnum

Status of the listing: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.

ValuesDONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUT
400objectError 400 response

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/finops/costExplorer/dimensionValue \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "errors": [ { "class": "string", "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "result": [ { "dimension": "string", "values": [ "string" ] } ], "status": "DONE"}

Get a dimension values listing and its resultBeta

GET
/v2/finops/costExplorer/dimensionValue/{dimensionValueId}

Returns the status of a listing started with POST /v2/finops/costExplorer/dimensionValue. Poll this route until the status is DONE or ERROR. The result is set when the status is DONE.

Returns 404 when:

  • the account has no listing with this identifier;
  • the listing has expired.

Path parameters

dimensionValueId
required
stringuuid

Dimension value ID

Response

200DimensionValueTasksuccessful operation
createdAt
read-only
stringdate-time

Date when the listing was started

errors
read-only
TaskError[]

Errors that ended the listing. Empty unless the status is ERROR.

id
read-only
stringuuid

Unique identifier of the listing

result
read-only
DimensionValueList[]

Values of each dimension, in the order of GET /v2/finops/costExplorer/dimension. Null unless the status is DONE.

status
read-only
TaskStatusEnum

Status of the listing: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.

ValuesDONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUT

Example uses dimensionValueId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/finops/costExplorer/dimensionValue/{dimensionValueId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "errors": [ { "class": "string", "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "result": [ { "dimension": "string", "values": [ "string" ] } ], "status": "DONE"}