Exporting billing data to a bucket

Objective

OVHcloud can push your billing data, converted to the FOCUS open standard, to an S3¹-compatible object storage bucket that you own. Once configured, the export runs automatically every day: no manual download, no portal click — your data lands in your bucket as a CSV file ready for your FinOps tooling.

This guide shows you how to create, track, update and remove that export configuration through the OVHcloud API.

Requirements

• An active OVHcloud account with billing data.
• A valid OVHcloud API authentication token with permission to call the /finops routes. If needed, see First Steps with the OVHcloud APIs to create one. All requests below must be authenticated; the examples show the token as $OVH_API_TOKEN.
• An S3-compatible bucket you can write to, and a pair of credentials for it:
  • an access key and a secret key,
  • the bucket endpoint host (a host name without a http:// / https:// / s3:// scheme, e.g. s3.gra.io.cloud.ovh.net) and its region.

How the export works

The configuration is a declarative resource. You describe the target you want (your bucket, the daily hour, the file policy) and OVHcloud reconciles toward it:

1. You create the configuration with the bucket details (POST).
2. OVHcloud validates it by actually connecting to your bucket and checking it is reachable with the credentials you gave.
3. When validation succeeds, the resource becomes READY; if OVHcloud cannot reach your bucket, it becomes ERROR.
4. Every day, at the hour you chose, OVHcloud regenerates your data for the current month and uploads the file to your bucket.

Because validation involves a real connection test, OVHcloud handles creation and updates asynchronously: the API answers immediately with a status of CREATING (or UPDATING), and you poll the resource until it reaches READY.

All examples use the OVHcloud European API endpoint https://eu.api.ovh.com/v2. If your account is hosted in another region, use your regional API endpoint instead (for example https://ca.api.ovh.com/v2 for Canada).

Step 1 — Create the export configuration

Send a POST to /finops/bucketExport with your target specification.

curl -X POST "https://eu.api.ovh.com/v2/finops/bucketExport" \
  -H "Authorization: Bearer $OVH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetSpec": {
      "exportHour": 6,
      "filePolicy": "CREATE",
      "bucketConfiguration": {
        "accessKey": "MY_ACCESS_KEY",
        "secretKey": "MY_SECRET_KEY",
        "bucketName": "my-finops-export",
        "endpointURL": "s3.gra.io.cloud.ovh.net",
        "region": "gra",
        "pathPrefix": "./"
      }
    }
  }'

targetSpec fields

The response

The API answers 201 Created with the resource. Note the id (you will use it to track and manage the configuration) and the resourceStatus, which starts at CREATING:

{
  "id": "f556df9c-a52e-4bc1-8895-e3589cbba0be",
  "resourceStatus": "CREATING",
  "checksum": "9b2c5d6e0f1a2b3c4d5e6f7a8b9c0d1e",
  "targetSpec": {
    "exportHour": 6,
    "filePolicy": "CREATE",
    "bucketConfiguration": {
      "accessKey": "MY_ACCESS_KEY",
      "secretKey": "***",
      "bucketName": "my-finops-export",
      "endpointURL": "s3.gra.io.cloud.ovh.net",
      "region": "gra",
      "pathPrefix": "./"
    }
  },
  "currentState": { "...": "same shape as targetSpec" },
  "currentTasks": [
    {
      "id": "5a1b...",
      "type": "CREATE_BUCKET_EXPORT",
      "status": "PENDING",
      "link": "/finops/bucketExport/f556df9c-a52e-4bc1-8895-e3589cbba0be"
    }
  ]
}

Step 2 — Follow the provisioning until it is ready

Creation is asynchronous. Poll the resource by its id until resourceStatus is no longer CREATING:

curl "https://eu.api.ovh.com/v2/finops/bucketExport/f556df9c-a52e-4bc1-8895-e3589cbba0be" \
  -H "Authorization: Bearer $OVH_API_TOKEN"

• READY — OVHcloud reached your bucket and the configuration is live. The next daily run will upload your data.
• ERROR — validation failed (most often OVHcloud could not reach your bucket with the credentials you provided). See the Frequent errors section.

Inspecting the provisioning detail

Two read-only sub-resources let you see exactly what happened.

List the tasks (the units of work OVHcloud ran, including finished ones):

curl "https://eu.api.ovh.com/v2/finops/bucketExport/f556df9c-a52e-4bc1-8895-e3589cbba0be/task" \
  -H "Authorization: Bearer $OVH_API_TOKEN"

List the lifecycle events (a human-readable timeline):

curl "https://eu.api.ovh.com/v2/finops/bucketExport/f556df9c-a52e-4bc1-8895-e3589cbba0be/event" \
  -H "Authorization: Bearer $OVH_API_TOKEN"

A task carries an errors array; when a connection test fails, its message tells you why.

Step 3 — Retrieve your exported files

Once the configuration is READY, OVHcloud uploads a CSV file to your bucket once a day, at the exportHour you set (UTC).

• Content: your billing data converted to the FOCUS 1.3 standard, as CSV.
• Window: each run covers the current calendar month up to that moment (from the 1st of the month to now). The file therefore grows through the month as OVHcloud ingests new billing data.

File layout in your bucket

The object key depends on your filePolicy:

A pathPrefix of "./" writes at the bucket root (no extra folder). For example, with pathPrefix: "./" and the default CREATE policy, your data for 15 June 2026 lands at:

<your-nichandle>/2026/06/15/focus.csv

Managing an existing configuration

Update it

Send a PUT to /finops/bucketExport/{id} with the complete targetSpec you want (the new spec fully replaces the previous one). As with creation, OVHcloud validates the update asynchronously: the response comes back as UPDATING, and you poll until READY.

curl -X PUT "https://eu.api.ovh.com/v2/finops/bucketExport/f556df9c-a52e-4bc1-8895-e3589cbba0be" \
  -H "Authorization: Bearer $OVH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetSpec": {
      "exportHour": 8,
      "filePolicy": "CREATE",
      "bucketConfiguration": {
        "accessKey": "MY_ACCESS_KEY",
        "secretKey": "MY_SECRET_KEY",
        "bucketName": "my-finops-export",
        "endpointURL": "s3.gra.io.cloud.ovh.net",
        "region": "gra",
        "pathPrefix": "./"
      }
    }
  }'

List your configurations

curl "https://eu.api.ovh.com/v2/finops/bucketExport" \
  -H "Authorization: Bearer $OVH_API_TOKEN"

The list is paginated. When more results are available, the response carries an X-Pagination-Cursor-Next header; pass it back as the X-Pagination-Cursor header to fetch the next page.

Delete it

curl -X DELETE "https://eu.api.ovh.com/v2/finops/bucketExport/f556df9c-a52e-4bc1-8895-e3589cbba0be" \
  -H "Authorization: Bearer $OVH_API_TOKEN"

Deletion stops the daily export. OVHcloud does not remove the files already written to your bucket.

Reference: resource status values

Frequent errors

Most failures show up as a resource stuck in ERROR after create or update, because OVHcloud validates the configuration by actually connecting to your bucket. Always start by reading the task errors (Step 2) — the message names the cause. The most common ones:

Go further

The exported file follows the FOCUS 1.3 CSV standard — refer to the official FOCUS specification to interpret each column.

Join our Discord community to ask questions and share feedback.

¹: S3 is a trademark of Amazon Technologies, Inc. OVHcloud's service is not sponsored by, endorsed by, or otherwise affiliated with Amazon Technologies, Inc.