Cost Explorer
All operations require authentication.
Start the computation of a cost breakdownBeta
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 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.
AUDCADCZKEURGBPINRLTLMADPLNPOINTSSGDTNDUSDXOFFilters 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.
Start of the range, included
Finest width of a period. The computation uses a coarser one when the range holds more than 744 periods of this width.
DAYHOURMONTHKey of the dimension whose values split the cost into series, as GET /v2/finops/costExplorer/dimension lists it. Null groups by CATEGORY.
End of the range, excluded. It must be after from.
Response
Date when the computation was started
Errors that ended the computation. Empty unless the status is ERROR.
Unique identifier of the computation
Cost breakdown. Null unless the status is DONE.
Status of the computation: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.
DONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUTReads your token from $OVH_TOKEN
$ curl https:/ / api.eu.ovhcloud.com/ v2/ finops/ costExplorer/ breakdown \
-H "authorization: Bearer $OVH_TOKEN"{ "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
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
Breakdown ID
Response
Date when the computation was started
Errors that ended the computation. Empty unless the status is ERROR.
Unique identifier of the computation
Cost breakdown. Null unless the status is DONE.
Status of the computation: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.
DONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUTExample uses breakdownId = 00000000-0000-0000-0000-000000000000
$ curl https:/ / api.eu.ovhcloud.com/ v2/ finops/ costExplorer/ breakdown/ {breakdownId} \
-H "authorization: Bearer $OVH_TOKEN"{ "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
Headers
Pagination cursor
Pagination size
Response
Identifier of the dimension, for example CATEGORY, as the groupBy and the filters of a cost breakdown take it
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"[ { "key": "string", "label": "string" }]
Start the listing of the values of every dimension in the cost lines of a rangeBeta
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)
Start of the range, included
End of the range, excluded. It must be after from.
Response
Date when the listing was started
Errors that ended the listing. Empty unless the status is ERROR.
Unique identifier of the listing
Values of each dimension, in the order of GET /v2/finops/costExplorer/dimension. Null unless the status is DONE.
Status of the listing: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.
DONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUTReads your token from $OVH_TOKEN
$ curl https:/ / api.eu.ovhcloud.com/ v2/ finops/ costExplorer/ dimensionValue \
-H "authorization: Bearer $OVH_TOKEN"{ "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
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
Dimension value ID
Response
Date when the listing was started
Errors that ended the listing. Empty unless the status is ERROR.
Unique identifier of the listing
Values of each dimension, in the order of GET /v2/finops/costExplorer/dimension. Null unless the status is DONE.
Status of the listing: PENDING, RUNNING, DONE or ERROR. DONE and ERROR are final.
DONEERRORPENDINGRUNNINGSCHEDULEDWAITING_USER_INPUTExample uses dimensionValueId = 00000000-0000-0000-0000-000000000000
$ curl https:/ / api.eu.ovhcloud.com/ v2/ finops/ costExplorer/ dimensionValue/ {dimensionValueId} \
-H "authorization: Bearer $OVH_TOKEN"{ "createdAt": "2024-01-01T12:00:00Z", "errors": [ { "class": "string", "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "result": [ { "dimension": "string", "values": [ "string" ] } ], "status": "DONE"}