Billing FinOps API

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 pageOpen in new context 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.

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.

   Note

   This is an optional step that aims at simplifying your usage of the API.

   Code
   export SCW_SECRET_KEY="<API secret key>"
   export SCW_ORGANIZATION_ID="<Scaleway 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.

   Code
   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 documentationOpen in new context
• Our Slack CommunityOpen in new context
• Our support ticketing systemOpen in new context.