openapi: 3.1.0
info:
title: Billing FinOps API
description: |-
Scaleway's Billing - FinOps API enables you to programmatically access raw consumption data generated by the usage of Scaleway resources. You can retrieve all charges for one or more organizations or projects, and filter based on SKU, invoice ID, resource ID, etc.
## Concepts
Refer to our [dedicated concepts page](https://www.scaleway.com/en/docs/billing/concepts/) to find definitions of all concepts and terminology related to Billing.
### Difference between FinOps API data and Consumption API data
The Consumption API allows you to get the data used in your invoice, whereas the FinOps API enables you to retrieve raw consumption data generated by the usage of Scaleway resources.
The FinOps API might show slight differences with the consumption/billing data if you try to reconcile both. This is due to the fact that FinOps data is calculated differently from consumption data. The differences in how the data is rounded and aggregated might result in small cost discrepancies when comparing both data sources.
- A Scaleway account logged into the [console](https://console.scaleway.com/organization)
- Created an [API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) with sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page
- [Installed `curl`](https://curl.se/download.html)
- Configured your environment variables
## Quickstart
1. Open a terminal and run the following command to export your API secret key and Organization ID. Remember to replace the placeholders with your own corresponding values.
This is an optional step that aims at simplifying your usage of the API.
```bash
export SCW_SECRET_KEY=""
export SCW_ORGANIZATION_ID=""
```
2. Run the following command to obtain detailed charges for a specific resource between two dates. Remember to replace the resource identifier and date placeholders with your own corresponding values.
```bash
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
-H "Content-Type: application/json" \
"https://api.scaleway.com/billing/v2beta1/charges?organization_id=$SCW_ORGANIZATION_ID&resourceIds=YourResourceId&startDateAfter=2026-05-26T00:00:00.000000000Z&endDateBefore=2026-05-30T00:00:00.000000000Z"
```
## Technical information
### Availability of `resource_name`
The `resource_name` is only available if the related product had the transfer of this information enabled in the backend when creating the resource.
### Pagination
The API uses pagination to split a large set of results into smaller, manageable pages that can be retrieved one at a time.
- The response includes a `next_page_token` whenever additional items are available.
- To retrieve the next page, pass that token in the subsequent request.
### Clamping: retrieving partial charges for a selected period
Clamping automatically cuts a charge that spans a longer period (e.g. the whole month) into the exact slice that falls inside the time window you asked for.
When you set `"clampToTimeRange": true`, the API returns a partial charge that represents only the portion of the resource’s usage that overlaps with your requested dates.
When you set `"clampToTimeRange": false`, the API only returns charges whose entire start‑ and end‑dates are inside the requested window. When a charge starts before the window (or ends after it), the result is empty.
### IAM requirements
Keep in mind that:
- You must have appropriate IAM permissions to manage billing. If you are the Owner of the Organization, you will automatically have these permissions. Otherwise, you will need a policy giving you the `BillingManager` permission set. If you were previously a Billing Administrator, you will automatically have been migrated to the `BillingAdministrator` group when you activated IAM, which gives you the appropriate permissions.
- You only need `BillingReadOnly` permissions to query consumption.
## Going further
For more help using Scaleway’s Billing API, check out the following resources:
- Our [main documentation](https://www.scaleway.com/en/docs/billing/)
- Our [Slack Community](https://www.scaleway-community.slack.com/)
- Our [support ticketing system](https://www.scaleway.com/en/docs/account/how-to/open-a-support-ticket/).
version: v2beta1
servers:
- url: https://api.scaleway.com
tags:
- name: Charges
description: A charge details a gross usage or commitment.
components:
schemas:
scaleway.billing.v2beta1.Charge:
type: object
properties:
organization_id:
type: string
description: ID of the charged organization. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
project_id:
type: string
description: ID of the charged project. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
sku:
type: string
description: ID of the SKU the charge is priced with.
invoice_id:
type: string
description: ID of the invoice including the charge. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
resource_id:
type: string
description: ID of the resource that incurs the charge.
resource_name:
type: string
description: Optional display name assigned to the resource that incurs
the charge.
nullable: true
price:
type: object
description: Price of the charge.
properties:
currency_code:
type: string
units:
type: integer
format: int64
nanos:
type: integer
format: int32
x-properties-order:
- currency_code
- units
- nanos
start_date:
type: string
description: Start date of the charge. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
end_date:
type: string
description: End date of the charge, included. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
updated_at:
type: string
description: Date the charge was last updated. (RFC 3339 format)
format: date-time
example: "2022-03-22T12:34:56.123456Z"
nullable: true
x-properties-order:
- organization_id
- project_id
- sku
- invoice_id
- resource_id
- resource_name
- price
- start_date
- end_date
- updated_at
scaleway.billing.v2beta1.ListChargesResponse:
type: object
properties:
charges:
type: array
description: Paginated matching charges.
items:
$ref: '#/components/schemas/scaleway.billing.v2beta1.Charge'
next_page_token:
type: string
description: Page token to use with following call to keep listing charges
if there are more.
nullable: true
x-properties-order:
- charges
- next_page_token
securitySchemes:
scaleway:
in: header
name: X-Auth-Token
type: apiKey
paths:
/billing/v2beta1/charges:
get:
tags:
- Charges
operationId: ListCharges
summary: List charges
description: List charges for organizations or projects. You must specify at
least `organization_ids` or `project_ids`.
parameters:
- in: query
name: order_by
description: Sort order of charges in the response.
schema:
type: string
enum:
- start_date_asc
- start_date_desc
x-enum-descriptions:
values:
start_date_asc: Order by start date (ascending chronological order)
start_date_desc: Order by start date (descending chronological order)
default: start_date_asc
- in: query
name: page_token
description: Token returned by previous call to list next paginated charges,
omitted for first page.
schema:
type: string
- in: query
name: page_size
description: Number of charges to return per page.
schema:
type: integer
format: uint32
- in: query
name: start_date_after
description: Minimum start date of charges to filter for, defaults to the
start of the billing period. (RFC 3339 format)
schema:
type: string
format: date-time
example: "2022-03-22T12:34:56.123456Z"
- in: query
name: end_date_before
description: Maximum end date of charges to filter for, defaults to the end
of the billing period. (RFC 3339 format)
schema:
type: string
format: date-time
example: "2022-03-22T12:34:56.123456Z"
- in: query
name: invoice_ids
description: Invoice IDs to filter for, only charges from these invoices will
be returned. (UUID format)
schema:
type: array
example:
- 6170692e-7363-616c-6577-61792e636f6d
items:
type: string
- in: query
name: organization_id
description: Organization ID to filter for, only charges for this organization
will be returned.
required: true
schema:
type: string
- in: query
name: project_ids
description: Project IDs to filter for, only charges for these projects will
be returned. (UUID format)
schema:
type: array
example:
- 6170692e-7363-616c-6577-61792e636f6d
items:
type: string
- in: query
name: resource_ids
description: Resource IDs to filter for, only charges for these resources
will be returned.
schema:
type: array
items:
type: string
- in: query
name: resource_names
description: Resource display names to filter for, only charges for these
resources will be returned.
schema:
type: array
items:
type: string
- in: query
name: skus
description: SKU IDs to filter for, only charges for these SKUs will be returned.
schema:
type: array
items:
type: string
- in: query
name: clamp_to_time_range
description: Clamp charges to the requested time range.
schema:
type: boolean
responses:
"200":
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/scaleway.billing.v2beta1.ListChargesResponse'
security:
- scaleway: []
x-codeSamples:
- lang: cURL
source: |-
curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/billing/v2beta1/charges?organization_id=string"
- lang: HTTPie
source: |-
http GET "https://api.scaleway.com/billing/v2beta1/charges" \
X-Auth-Token:$SCW_SECRET_KEY \
organization_id==string