Usage and costs¶

Measured usage, statements, the rate card and the cost explorer. Provisional.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

Explore the organization's costs¶

GET /v1/orgs/{org_id}/costs

A month's provisional cost so far by project, service, location or one tag key's values, day by day, with last month's total and an estimate of this month's.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`group_by`	query	string	project	No
`org_id`	path	string		No
`period`	query	string		Yes
`project`	query	string		Yes

Responses

200 OK

application/jsonapplication/json

{
    "as_of": "2022-04-13T15:42:05.901Z",
    "currency": "string",
    "group_by": "string",
    "groups": [
        {
            "amount": "string",
            "days": [
                {
                    "amount": "string",
                    "day": "string"
                }
            ],
            "key": "string",
            "label": "string"
        }
    ],
    "period": "string",
    "previous": {
        "groups": [
            {
                "amount": "string",
                "key": "string"
            }
        ],
        "period": "string",
        "reason": "no_data",
        "total": "string"
    },
    "project": "string",
    "projection": {
        "amount": "string",
        "basis_days": 0,
        "reason": "too_few_days"
    },
    "provisional": true,
    "services": [
        {
            "key": "string",
            "label": "string"
        }
    ],
    "tag_keys": [
        "string"
    ],
    "total": "string",
    "unrated": [
        {
            "location": "string",
            "metric": "string",
            "quantity": "string",
            "unit": "string"
        }
    ],
    "untagged": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a project's usage¶

GET /v1/orgs/{org_id}/projects/{project_id}/usage

The project's provisional usage quantities for a time window. Never prices.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`from`	query	string		Yes
`group_by`	query	string		Yes
`org_id`	path	string		No
`project_id`	path	string		No
`to`	query	string		Yes

Responses

200 OK

application/jsonapplication/json

{
    "from": "2022-04-13T15:42:05.901Z",
    "group_by": "string",
    "items": [
        {
            "bounded": true,
            "location": "string",
            "metric": "string",
            "project": "string",
            "quantity": "string",
            "resource_type": "string",
            "unit": "string"
        }
    ],
    "provisional": true,
    "quality": "string",
    "sources": [
        {
            "data_as_of": "2022-04-13T15:42:05.901Z",
            "location": "string",
            "status": "ok"
        }
    ],
    "to": "2022-04-13T15:42:05.901Z"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get the rate card in force¶

GET /v1/orgs/{org_id}/rate-card

The prices usage is rated at now, and the next published change, if any.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "currency": "string",
    "in_force": {
        "currency": "string",
        "effective_from": "2022-04-13T15:42:05.901Z",
        "lines": [
            {
                "dimension": {
                    "key": "string",
                    "value": "string"
                },
                "location": "string",
                "metric": "string",
                "unit_price": "string"
            }
        ],
        "version": 0
    },
    "next": null,
    "provisional": true
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List the organization's statements¶

GET /v1/orgs/{org_id}/statements

One statement per calendar month (UTC): open while it runs, then closed.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`limit`	query	integer		Yes
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "as_of": "2022-04-13T15:42:05.901Z",
            "closed_at": "2022-04-13T15:42:05.901Z",
            "closes_at": "2022-04-13T15:42:05.901Z",
            "currency": "string",
            "gaps": [
                {
                    "from": "2022-04-13T15:42:05.901Z",
                    "hours": "string",
                    "kind": "skipped",
                    "location": "string",
                    "project": "string",
                    "to": "2022-04-13T15:42:05.901Z"
                }
            ],
            "id": "string",
            "lines": 0,
            "period": "string",
            "period_end": "2022-04-13T15:42:05.901Z",
            "period_start": "2022-04-13T15:42:05.901Z",
            "provisional": true,
            "state": "open",
            "total": "string",
            "unrated_lines": 0
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a statement¶

GET /v1/orgs/{org_id}/statements/{statement_id}

A month's cost by metric, location and rate, with adjustments for corrections of closed months.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`statement_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "adjustments_after": "2022-04-13T15:42:05.901Z",
    "as_of": "2022-04-13T15:42:05.901Z",
    "built_at": "2022-04-13T15:42:05.901Z",
    "closed_at": "2022-04-13T15:42:05.901Z",
    "closes_at": "2022-04-13T15:42:05.901Z",
    "currency": "string",
    "gaps": [
        {
            "from": "2022-04-13T15:42:05.901Z",
            "hours": "string",
            "kind": "skipped",
            "location": "string",
            "project": "string",
            "to": "2022-04-13T15:42:05.901Z"
        }
    ],
    "id": "string",
    "items": [
        {
            "amount": "string",
            "bounded": true,
            "dimension": {
                "key": "string",
                "value": "string"
            },
            "hours_from": "2022-04-13T15:42:05.901Z",
            "hours_to": "2022-04-13T15:42:05.901Z",
            "id": "string",
            "kind": "usage",
            "location": "string",
            "metric": "string",
            "observations": 0,
            "quantity": "string",
            "rate_version": 0,
            "rated": true,
            "unit": "string",
            "unit_price": "string",
            "usage_period": "string"
        }
    ],
    "lines": 0,
    "period": "string",
    "period_end": "2022-04-13T15:42:05.901Z",
    "period_start": "2022-04-13T15:42:05.901Z",
    "provisional": true,
    "state": "open",
    "total": "string",
    "unrated_lines": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Trace a statement line to its usage¶

GET /v1/orgs/{org_id}/statements/{statement_id}/lines/{line_id}/usage

The hourly usage observations a line counts; for an adjustment, the corrections and the values they replace.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`limit`	query	integer		Yes
`line_id`	path	string		No
`org_id`	path	string		No
`statement_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "counted": "added",
            "hour": "2022-04-13T15:42:05.901Z",
            "observation": "string",
            "precision": "exact",
            "quantity": "string",
            "supersedes": "string"
        }
    ],
    "next_cursor": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get the organization's usage¶

GET /v1/orgs/{org_id}/usage

Provisional usage quantities, such as instance hours and storage, for a time window, optionally grouped by project, location or resource type. Never prices.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`from`	query	string		Yes
`group_by`	query	string		Yes
`org_id`	path	string		No
`to`	query	string		Yes

Responses

200 OK

application/jsonapplication/json

{
    "from": "2022-04-13T15:42:05.901Z",
    "group_by": "string",
    "items": [
        {
            "bounded": true,
            "location": "string",
            "metric": "string",
            "project": "string",
            "quantity": "string",
            "resource_type": "string",
            "unit": "string"
        }
    ],
    "provisional": true,
    "quality": "string",
    "sources": [
        {
            "data_as_of": "2022-04-13T15:42:05.901Z",
            "location": "string",
            "status": "ok"
        }
    ],
    "to": "2022-04-13T15:42:05.901Z"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List the organization's usage exports¶

GET /v1/orgs/{org_id}/usage/exports

Every export asked for, newest first, with its month, its cutoff and whether it is ready to download.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`limit`	query	integer		Yes
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "as_of": "2022-04-13T15:42:05.901Z",
            "href": "string",
            "id": "string",
            "month": "string",
            "operation": {
                "href": "string",
                "id": "string"
            },
            "ready_at": "2022-04-13T15:42:05.901Z",
            "requested_at": "2022-04-13T15:42:05.901Z",
            "state": "preparing"
        }
    ],
    "next_cursor": "string",
    "provisional": true
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Export a month's usage¶

POST /v1/orgs/{org_id}/usage/exports

Asks for an export of a calendar month's hourly usage, every resource and metric, as it stands now. Accepted at once: follow the returned operation, then download the export from its href.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No

Request body

application/json202 Accepted

{
    "month": "string"
}

Responses

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Download a usage export¶

GET /v1/orgs/{org_id}/usage/exports/{export_id}

Once ready, the month's hourly usage as JSON lines: a header, one line per resource, metric and hour, and an end line with the totals. Every download of an export gives the same lines. Provisional until the shadow period ends.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`export_id`	path	string		No
`org_id`	path	string		No

Responses

200 OK

application/x-ndjsonapplication/json

"string"

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List the organization's usage gaps¶

GET /v1/orgs/{org_id}/usage/gaps

The hours in a time window whose usage is not known, per project and location, with their width. Usage never counts them as zero.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`from`	query	string		Yes
`org_id`	path	string		No
`to`	query	string		Yes

Responses

200 OK

application/jsonapplication/json

{
    "from": "2022-04-13T15:42:05.901Z",
    "items": [
        {
            "from": "2022-04-13T15:42:05.901Z",
            "hours": "string",
            "kind": "skipped",
            "location": "string",
            "project": "string",
            "to": "2022-04-13T15:42:05.901Z"
        }
    ],
    "provisional": true,
    "to": "2022-04-13T15:42:05.901Z"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get the organization's usage by month¶

GET /v1/orgs/{org_id}/usage/months

Provisional usage quantities per calendar month and metric, newest month first, including months older than the 13 months of hourly usage, which keep their totals. from and to are months (YYYY-MM), both included; by default the months of hourly usage up to this one. Never prices.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`cursor`	query	string		Yes
`from`	query	string		Yes
`limit`	query	integer		Yes
`org_id`	path	string		No
`to`	query	string		Yes

Responses

200 OK

application/jsonapplication/json

{
    "detail_from": "string",
    "from": "string",
    "items": [
        {
            "bounded": true,
            "metric": "string",
            "month": "string",
            "quantity": "string",
            "source": "hourly",
            "unit": "string"
        }
    ],
    "next_cursor": "string",
    "provisional": true,
    "quality": "string",
    "to": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Schemas¶

Accepted¶

Name	Type	Description
`operation`	OperationLink

CostDay¶

Name	Type	Description
`amount`	string \| null	Null when no hour of the day was rated.
`day`	string	A UTC day, `YYYY-MM-DD`.

CostGroup¶

Name	Type	Description
`amount`	string \| null	The rated hours' cost; null when none was rated.
`days`	Array<CostDay>
`key`	string \| null	The project (`prj_…`), the service, the location's slug or the tag's value (null: no location, or untagged).
`label`	string	The project's or location's name, or the service's label.

Costs¶

Name	Type	Description
`as_of`	string(date-time) \| null	Usage collected up to this time is counted.
`currency`	string \| null	ISO 4217; null before any statement was built.
`group_by`	string	`project`, `service`, `location` or `tag:`.
`groups`	Array<CostGroup>
`period`	string	The calendar month (UTC), `YYYY-MM`.
`previous`	Previous
`project`	string \| null	The project the answer is narrowed to.
`projection`	Projection
`provisional`	boolean	Usage is provisional until E10.
`services`	Array<Service>	Every service's key and label.
`tag_keys`	Array<string>	The tag keys to group by: those with cost this month or on a resource now.
`total`	string \| null	The rated usage's cost so far this month.
`unrated`	Array<Unrated>
`untagged`	string \| null	With `group_by=tag:`: the cost of hours without that key (also the group with a null key); otherwise null.

Dimension¶

Name	Type	Description
`key`	string	`flavor` or `volume_type`.
`value`	string

ExportBody¶

Name	Type	Description
`month`	string	The calendar month (UTC), `YYYY-MM`.

ExportOperation¶

Name	Type	Description
`href`	string
`id`	string	`op_…`

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

LineUsage¶

Name	Type	Description
`items`	Array<UsageRow>
`next_cursor`	string \| null

OperationLink¶

Name	Type	Description
`href`	string	Where to read the operation; also the `Location` header.
`id`	string	The operation's ID (`op_…`).
`state`	string \| null	Its state when accepted, normally `queued`.

Previous¶

Name	Type	Description
`groups`	Array<PreviousGroup>
`period`	string
`reason`	string \| null	`currency_changed`: last month was priced in another currency.
`total`	string \| null	Last month's total; null with a `reason`.

PreviousGroup¶

Name	Type	Description
`amount`	string \| null
`key`	string \| null

Projection¶

Name	Type	Description
`amount`	string \| null	The month to date plus the mean of the last complete days (at most 7) for each whole day left; null with a `reason`.
`basis_days`	integer
`reason`	string \| null

RateCard¶

Name	Type	Description
`currency`	string \| null
`in_force`	RateVersion
`next`	RateVersion
`provisional`	boolean

RateLine¶

Name	Type	Description
`dimension`	Dimension
`location`	string \| null	None: every location.
`metric`	string
`unit_price`	string

RateVersion¶

Name	Type	Description
`currency`	string \| null	ISO 4217. It changes only from 00:00 UTC on the 1st of a month.
`effective_from`	string(date-time)
`lines`	Array<RateLine>
`version`	integer

Service¶

Name	Type	Description
`key`	string
`label`	string

Statement¶

Name	Type	Description
`adjustments_after`	string(date-time) \| null	Adjustments count corrections collected after this time.
`as_of`	string(date-time) \| null	Usage collected up to this time is counted.
`built_at`	string(date-time) \| null
`closed_at`	string(date-time) \| null
`closes_at`	string(date-time)
`currency`	string	ISO 4217 code.
`gaps`	Array<StatementGap>	The month's hours whose usage is not known, as the last build saw them; a closed statement keeps those it closed with. Never counted as zero; hours derived later reach the next statement as adjustments.
`id`	string	`stm_…`
`items`	Array<StatementLine>
`lines`	integer
`period`	string	The calendar month (UTC), `YYYY-MM`.
`period_end`	string(date-time)
`period_start`	string(date-time)
`provisional`	boolean	True while the usage behind it is provisional.
`state`	string	`open` while the month runs and until its close; `closed` is final.
`total`	string	The rated lines' amounts added up, a decimal as text.
`unrated_lines`	integer	Lines of usage with no rate; not in the total.

StatementGap¶

Name	Type	Description
`from`	string(date-time)
`hours`	string	Its width, a decimal as text.
`kind`	string
`location`	string \| null
`project`	string	The project (`prj_…`).
`to`	string(date-time)

StatementLine¶

Name	Type	Description
`amount`	string \| null
`bounded`	boolean	An hour holds a boundary known only between two readings.
`dimension`	Dimension
`hours_from`	string(date-time)
`hours_to`	string(date-time)
`id`	string	`stl_…`
`kind`	string	`adjustment`: a correction of a closed month, by the difference.
`location`	string \| null
`metric`	string
`observations`	integer
`quantity`	string	A decimal as text; negative for a correction downwards.
`rate_version`	integer \| null
`rated`	boolean	False when no rate applies: no price and no amount.
`unit`	string
`unit_price`	string \| null
`usage_period`	string	The month the hours belong to, `YYYY-MM`.

StatementList¶

Name	Type	Description
`items`	Array<StatementSummary>
`next_cursor`	string \| null

StatementSummary¶

Name	Type	Description
`as_of`	string(date-time) \| null	Usage collected up to this time is counted.
`closed_at`	string(date-time) \| null
`closes_at`	string(date-time)
`currency`	string	ISO 4217 code.
`gaps`	Array<StatementGap>	The month's hours whose usage is not known, as the last build saw them; a closed statement keeps those it closed with. Never counted as zero; hours derived later reach the next statement as adjustments.
`id`	string	`stm_…`
`lines`	integer
`period`	string	The calendar month (UTC), `YYYY-MM`.
`period_end`	string(date-time)
`period_start`	string(date-time)
`provisional`	boolean	True while the usage behind it is provisional.
`state`	string	`open` while the month runs and until its close; `closed` is final.
`total`	string	The rated lines' amounts added up, a decimal as text.
`unrated_lines`	integer	Lines of usage with no rate; not in the total.

Unrated¶

Name	Type	Description
`location`	string \| null
`metric`	string
`quantity`	string	Usage with no rate. Not in any amount, never a zero cost.
`unit`	string

Usage¶

Name	Type	Description
`from`	string(date-time)	The window's start (included).
`group_by`	string \| null
`items`	Array<UsageQuantity>
`provisional`	boolean
`quality`	string
`sources`	Array<UsageSource>
`to`	string(date-time)	The window's end (excluded).

UsageExportItem¶

Name	Type	Description
`as_of`	string(date-time)	Usage collected up to this time is in the export.
`href`	string	Where to download it once ready.
`id`	string	`uex_…`
`month`	string	The calendar month (UTC), `YYYY-MM`.
`operation`	ExportOperation
`ready_at`	string(date-time) \| null
`requested_at`	string(date-time)
`state`	string	`ready`: download it from `href`; `failed`: its operation ended without it (the month's hourly usage was removed meanwhile).

UsageExportList¶

Name	Type	Description
`items`	Array<UsageExportItem>
`next_cursor`	string \| null
`provisional`	boolean

UsageGap¶

Name	Type	Description
`from`	string(date-time)	The gap's start in the window (included).
`hours`	string	Its width in the window, a decimal as text.
`kind`	string	`skipped`: hours the ledger left behind, which a repair can still derive; `lost`: hours before the change log's reach, unknown for ever; `pending`: hours not derived yet, more than six hours after they ended.
`location`	string \| null
`project`	string	The project (`prj_…`).
`to`	string(date-time)	The gap's end in the window (excluded).

UsageGaps¶

Name	Type	Description
`from`	string(date-time)
`items`	Array<UsageGap>
`provisional`	boolean
`to`	string(date-time)

UsageMonthItem¶

Name	Type	Description
`bounded`	boolean	Whether an hour in the month has a start or end known only between two readings rather than exactly.
`metric`	string
`month`	string	The calendar month (UTC), `YYYY-MM`.
`quantity`	string	A decimal, as text.
`source`	string	`hourly`: summed from the hourly usage, which can be exported; `monthly_totals`: the month's totals, kept for ever after its hourly usage was removed.
`unit`	string

UsageMonths¶

Name	Type	Description
`detail_from`	string	The oldest month whose hourly usage is kept (13 months); earlier months have their totals only.
`from`	string	The first month (included), `YYYY-MM`.
`items`	Array<UsageMonthItem>
`next_cursor`	string \| null
`provisional`	boolean
`quality`	string
`to`	string	The last month (included), `YYYY-MM`.

UsageQuantity¶

Name	Type	Description
`bounded`	boolean	Whether an hour in the sum has a start or end known only between two readings rather than exactly.
`location`	string \| null	Grouped by location.
`metric`	string	Such as `instance.hours` or `ram.gb_hours`.
`project`	string	Grouped by project: the project (`prj_…`).
`quantity`	string	A decimal, as text.
`resource_type`	string \| null	Grouped by resource type.
`unit`	string

UsageRow¶

Name	Type	Description
`counted`	string	`removed`: an earlier value an adjustment takes back.
`hour`	string(date-time)
`observation`	string	`uob_…`
`precision`	string
`quantity`	string
`supersedes`	string \| null	The observation this one corrects.

UsageSource¶

Name	Type	Description
`data_as_of`	string(date-time) \| null
`location`	string
`status`	string	`pending`: no hour derived there yet.

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string