openapi: 3.1.0
info:
  title: Environmental Footprint API
  description: |-
    The Environmental Footprint API offers tools that help monitor your environmental impact using Scaleway's services.

    (switchcolumn)
    (switchcolumn)

    ## Calculation

    Refer to our dedicated [Environmental Footprint calculation breakdown](/environmental-footprint/additional-content/environmental-footprint-calculator/) documentation page for more information on how we measure your environmental footprint.

    (switchcolumn)
    (switchcolumn)

    ## Quickstart

    1. Configure your environment variables.

        ```bash
        export $SCW_ORGANIZATION_ID=<your-organization-ID>
        export $SCW_SECRET_KEY="<secret-key>"
        ```

    1. Run the query below to retrieve a list of available reports:
        ```bash
        curl \
        -H "X-Auth-Token: ${SCW_SECRET_KEY}" \
        "https://api.scaleway.com/environmental-footprint/v1alpha1/reports/availability?\
        organization_id=${SCW_ORGANIZATION_ID}&\
        start_date=<start-date>"
        ```

        You can add the following parameters to your endpoint:

        | Parameter        | Description                                   |
        | :--------------- | :--------------------------------------       |
        | `organization_id` | **REQUIRED** Your organization ID. |
        | `start_date`| **REQUIRED** The start date of the query period. The date should not be before 2024-10-01. The date should follow the ISO 8601 format. For example: `2025-07-01T00:00:00Z` |
        | `end_date`  | The end date of the query period. Defaults to the current day if not set. |

    2. Run the query below to retrieve a specific impact report.

        ```bash
        curl \
          -H "X-Auth-Token: ${SCW_SECRET_KEY}" \
          -d "{
            \"organization_id\": \"${SCW_ORGANIZATION_ID}\",
            \"type\": \"<report-type>\",
            \"date\": \"<report-date>\"
          }" \
          "https://api.scaleway.com/environmental-footprint/v1alpha1/reports/download" \
          | jq -r '.content' \
          | base64 -d \
          > /tmp/report.pdf
        ```
        You can add the following parameters to your endpoint:

        | Parameter        | Description                                   |
        | :--------------- | :--------------------------------------       |
        | `organization_id` | **REQUIRED** Your organization ID.  |
        | `date`| **REQUIRED** The date of the requested report. The date should not be before 2024-10-01 |
        | `type` | The report type. Can be `monthly` or `yearly` |

    3. Open the report.

        <Tabs>
          <TabsTab label="With Linux">
          ```bash
          xdg-open /tmp/report.pdf
          ```
          </TabsTab>
          <TabsTab label="With MacOS">
          ```bash
          open /tmp/report.pdf
          ```
          </TabsTab>
          </Tabs>


    4. Run the query below to retrieve specific impact data for your Organization. You can add the parameters of your choice in the endpoint to filter the query by project ID, region, zone, service category, and/or product category. In the example below we retrieve the impact data of all Elastic Metal servers in the Organization.

        ```bash
        curl -H "X-Auth-Token: ${SCW_SECRET_KEY}" "https://api.scaleway.com/environmental-footprint/v1alpha1/data/query?organization_id=${SCW_ORGANIZATION_ID}&start_date=<start_date>&product_categories=elastic_metal"
        ```

        | Parameter        | Description                                   |
        | :--------------- | :--------------------------------------       |
        | `organization_id` | **REQUIRED** Your organization ID. |
        | `start_date`| The start date of the query period. The date should not be before 2024-10-01. |
        | `product_categories` | List of product categories of the products for which you want to retrieve impact data. Example: `elastic_metal`. |

        <Message type="tip">
          Refer to the [Retrieve detailed impact data](#path-metrics-retrieve-detailed-impact-data) endpoint reference for an extensive list of available parameters and corresponding values.
        </Message>

        If the request was successful you will see a response like the following:

        ```json
        {
          "start_date": "2025-07-01T00:00:00Z",
          "end_date": "2025-07-04T00:00:00Z",
          "total_impact": {
            "kg_co2_equivalent": 2.453914,
            "m3_water_usage": 0.016715
          },
          "projects": [
            {
              "project_id": <project_id>,
              "total_project_impact": {
                "kg_co2_equivalent": 2.453914,
                "m3_water_usage": 0.016715
              },
              "regions": [
                {
                  "region": "fr-par",
                  "total_region_impact": {
                    "kg_co2_equivalent": 2.453914,
                    "m3_water_usage": 0.016715
                  },
                  "zones": [
                    {
                      "zone": "fr-par-2",
                      "total_zone_impact": {
                        "kg_co2_equivalent": 2.453914,
                        "m3_water_usage": 0.016715
                      },
                      "skus": [
                        {
                          "sku": "/baremetal/em-a115x-ssd/monthly/run_par2",
                          "total_sku_impact": {
                            "kg_co2_equivalent": 2.058405,
                            "m3_water_usage": 0.003345
                          },
                          "service_category": "baremetal",
                          "product_category": "elastic_metal"
                        }
                      ]
                    }
                  ]
                },
              ]
            }
          ]
        }
        ```

      The response gives you the estimated impact for the projects, regions, zones, service categories, and product categories that match your filters.

    <Message type="important">
      Your environmental footprint data may change for the same consumption.

      This is due to updates in the energy mix of data center locations, adjustments to PUE, or enhancements in our calculation methodology. These updates ensure that your reports reflect the most accurate and up-to-date information, enhancing transparency and trust in our reporting system.
    </Message>

    (switchcolumn)
    <Message type="requirement">
    - You have a [Scaleway account](https://console.scaleway.com/) and you know your Organization ID
    - You have created an [API key](https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/permission-sets/) to perform the actions described on this page
    - You know your [Organization ID](https://console.scaleway.com/organization/settings)
    - You have [installed `curl`](https://curl.se/download.html)
    </Message>
    (switchcolumn).
  version: v1alpha1
servers:
- url: https://api.scaleway.com
tags:
- name: Reports
  description: List and download impact reports for your Scaleway projects.
- name: Metrics
  description: Query impact metrics associated with your Scaleway projects.
components:
  schemas:
    google.protobuf.Timestamp:
      type: string
      format: date-time
      nullable: true
    scaleway.environmental_footprint.v1alpha1.ImpactDataResponse:
      type: object
      properties:
        start_date:
          type: string
          description: Start date of the impact data period (inclusive). (RFC 3339
            format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        end_date:
          type: string
          description: End date of the impact data period (exclusive). (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        total_impact:
          type: object
          description: The total estimated impact across all given Projects, regions,
            zones, service categories, and product categories during the given period.
          properties:
            kg_co2_equivalent:
              type: number
              description: The estimated carbon emissions in kilograms of CO₂ equivalent
                (kgCO₂e).
              format: float
            m3_water_usage:
              type: number
              description: The estimated water consumption in cubic meters (m³).
              format: float
          x-properties-order:
          - kg_co2_equivalent
          - m3_water_usage
        projects:
          type: array
          description: List of estimated impact values per Project.
          items:
            $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.ProjectImpact'
      x-properties-order:
      - start_date
      - end_date
      - total_impact
      - projects
    scaleway.environmental_footprint.v1alpha1.ImpactReportAvailability:
      type: object
      properties:
        month_summary_reports:
          type: array
          description: The list of calendar months for which impact reports are available.
            (RFC 3339 format)
          example:
          - "2022-03-22T12:34:56.123456Z"
          items:
            $ref: '#/components/schemas/google.protobuf.Timestamp'
      required:
      - month_summary_reports
      x-properties-order:
      - month_summary_reports
    scaleway.environmental_footprint.v1alpha1.ProductCategory:
      type: string
      enum:
      - unknown_product_category
      - apple_silicon
      - block_storage
      - dedibox
      - elastic_metal
      - instances
      - object_storage
      default: unknown_product_category
    scaleway.environmental_footprint.v1alpha1.ProjectImpact:
      type: object
      properties:
        project_id:
          type: string
          description: ID of the project.
        total_project_impact:
          type: object
          description: The total estimated impact for this Project across all given
            regions, zones, service categories, and product categories during the
            given period.
          properties:
            kg_co2_equivalent:
              type: number
              description: The estimated carbon emissions in kilograms of CO₂ equivalent
                (kgCO₂e).
              format: float
            m3_water_usage:
              type: number
              description: The estimated water consumption in cubic meters (m³).
              format: float
          x-properties-order:
          - kg_co2_equivalent
          - m3_water_usage
        regions:
          type: array
          description: List of estimated impact values per region.
          items:
            $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.RegionImpact'
      x-properties-order:
      - project_id
      - total_project_impact
      - regions
    scaleway.environmental_footprint.v1alpha1.RegionImpact:
      type: object
      properties:
        region:
          type: string
          description: ID of the region.
        total_region_impact:
          type: object
          description: The total estimated impact for this region across all given
            zones, service categories, and product categories during the given period.
          properties:
            kg_co2_equivalent:
              type: number
              description: The estimated carbon emissions in kilograms of CO₂ equivalent
                (kgCO₂e).
              format: float
            m3_water_usage:
              type: number
              description: The estimated water consumption in cubic meters (m³).
              format: float
          x-properties-order:
          - kg_co2_equivalent
          - m3_water_usage
        zones:
          type: array
          description: List of estimated impact values per zone.
          items:
            $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.ZoneImpact'
      x-properties-order:
      - region
      - total_region_impact
      - zones
    scaleway.environmental_footprint.v1alpha1.ServiceCategory:
      type: string
      enum:
      - unknown_service_category
      - baremetal
      - compute
      - storage
      default: unknown_service_category
    scaleway.environmental_footprint.v1alpha1.SkuImpact:
      type: object
      properties:
        sku:
          type: string
          description: Unique ID of the combination of product, region and zone.
        total_sku_impact:
          type: object
          description: The total estimated impact for this SKU during the given period.
          properties:
            kg_co2_equivalent:
              type: number
              description: The estimated carbon emissions in kilograms of CO₂ equivalent
                (kgCO₂e).
              format: float
            m3_water_usage:
              type: number
              description: The estimated water consumption in cubic meters (m³).
              format: float
          x-properties-order:
          - kg_co2_equivalent
          - m3_water_usage
        service_category:
          type: string
          description: The service category associated with this SKU.
          enum:
          - unknown_service_category
          - baremetal
          - compute
          - storage
          default: unknown_service_category
        product_category:
          type: string
          description: The product category associated with this SKU.
          enum:
          - unknown_product_category
          - apple_silicon
          - block_storage
          - dedibox
          - elastic_metal
          - instances
          - object_storage
          default: unknown_product_category
      x-properties-order:
      - sku
      - total_sku_impact
      - service_category
      - product_category
    scaleway.environmental_footprint.v1alpha1.ZoneImpact:
      type: object
      properties:
        zone:
          type: string
          description: ID of the zone.
        total_zone_impact:
          type: object
          description: The total estimated impact for this zone across all given service
            categories, and product categories during the given period.
          properties:
            kg_co2_equivalent:
              type: number
              description: The estimated carbon emissions in kilograms of CO₂ equivalent
                (kgCO₂e).
              format: float
            m3_water_usage:
              type: number
              description: The estimated water consumption in cubic meters (m³).
              format: float
          x-properties-order:
          - kg_co2_equivalent
          - m3_water_usage
        skus:
          type: array
          description: List of estimated impact values per SKU.
          items:
            $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.SkuImpact'
      x-properties-order:
      - zone
      - total_zone_impact
      - skus
    scaleway.std.File:
      type: object
      properties:
        name:
          type: string
        content_type:
          type: string
        content:
          type: string
      x-properties-order:
      - name
      - content_type
      - content
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /environmental-footprint/v1alpha1/data/query:
    get:
      tags:
      - Metrics
      operationId: GetImpactData
      summary: Retrieve detailed impact data
      description: Retrieve detailed impact data for your Scaleway projects within
        a specified date range. Filter by project ID, region, zone, service category,
        and/or product category.
      parameters:
      - in: query
        name: organization_id
        description: The UUID of the Organization for which you want to download a
          report.
        required: true
        schema:
          type: string
          description: The UUID of the Organization for which you want to download
            a report.
      - in: query
        name: start_date
        description: Start date (inclusive) of the period for which you want to retrieve
          impact data (ISO 8601 format, e.g., 2025-05-01T00:00:00Z). (RFC 3339 format)
        schema:
          type: string
          description: Start date (inclusive) of the period for which you want to
            retrieve impact data (ISO 8601 format, e.g., 2025-05-01T00:00:00Z). (RFC
            3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: end_date
        description: End date (exclusive) of the period for which you want to retrieve
          impact data (ISO 8601 format, with time in UTC, `YYYY-MM-DDTHH:MM:SSZ`).
          Defaults to today's date. (RFC 3339 format)
        schema:
          type: string
          description: End date (exclusive) of the period for which you want to retrieve
            impact data (ISO 8601 format, with time in UTC, `YYYY-MM-DDTHH:MM:SSZ`).
            Defaults to today's date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: regions
        description: List of regions to filter by (\"fr-par\"). Defaults to all regions.
        schema:
          type: array
          description: List of regions to filter by (\"fr-par\"). Defaults to all
            regions.
          items:
            type: string
      - in: query
        name: zones
        description: List of zones to filter by (\"fr-par-1\"). Defaults to all zones.
        schema:
          type: array
          description: List of zones to filter by (\"fr-par-1\"). Defaults to all
            zones.
          items:
            type: string
      - in: query
        name: project_ids
        description: List of Project IDs to filter by. Defaults to all Projects in
          the Organization.
        schema:
          type: array
          description: List of Project IDs to filter by. Defaults to all Projects
            in the Organization.
          items:
            type: string
      - in: query
        name: service_categories
        description: List of service categories to filter by. Defaults to all service
          categories.
        schema:
          type: array
          description: List of service categories to filter by. Defaults to all service
            categories.
          items:
            $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.ServiceCategory'
      - in: query
        name: product_categories
        description: List of product categories to filter by. Defaults to all product
          categories.
        schema:
          type: array
          description: List of product categories to filter by. Defaults to all product
            categories.
          items:
            $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.ProductCategory'
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.ImpactDataResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/environmental-footprint/v1alpha1/data/query?organization_id=string&start_date=2022-03-22T12:34:56.123456Z"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/environmental-footprint/v1alpha1/data/query" \
            X-Auth-Token:$SCW_SECRET_KEY \
            organization_id==string \
            start_date==2022-03-22T12:34:56.123456Z
  /environmental-footprint/v1alpha1/reports/availability:
    get:
      tags:
      - Reports
      operationId: GetImpactReportAvailability
      summary: Get available impact reports
      description: Returns a list of dates of available impact reports.
      parameters:
      - in: query
        name: organization_id
        description: The UUID of the Organization for which you want to download a
          report.
        required: true
        schema:
          type: string
          description: The UUID of the Organization for which you want to download
            a report.
      - in: query
        name: start_date
        description: Start date of the search period (ISO 8601 format, with time in
          UTC, `YYYY-MM-DDTHH:MM:SSZ`). The date is inclusive. (RFC 3339 format)
        schema:
          type: string
          description: Start date of the search period (ISO 8601 format, with time
            in UTC, `YYYY-MM-DDTHH:MM:SSZ`). The date is inclusive. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: end_date
        description: End date of the search period (ISO 8601 format, with time in
          UTC, `YYYY-MM-DDTHH:MM:SSZ`). The date is exclusive. Defaults to today's
          date. (RFC 3339 format)
        schema:
          type: string
          description: End date of the search period (ISO 8601 format, with time in
            UTC, `YYYY-MM-DDTHH:MM:SSZ`). The date is exclusive. Defaults to today's
            date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.environmental_footprint.v1alpha1.ImpactReportAvailability'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/environmental-footprint/v1alpha1/reports/availability?organization_id=string&start_date=2022-03-22T12:34:56.123456Z"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/environmental-footprint/v1alpha1/reports/availability" \
            X-Auth-Token:$SCW_SECRET_KEY \
            organization_id==string \
            start_date==2022-03-22T12:34:56.123456Z
  /environmental-footprint/v1alpha1/reports/download:
    post:
      tags:
      - Reports
      operationId: DownloadImpactReport
      summary: Download PDF impact report
      description: Download a Scaleway impact PDF report with detailed impact data
        for your Scaleway projects.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.std.File'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organization_id:
                  type: string
                  description: The UUID of the Organization for which you want to
                    download a report.
                date:
                  type: string
                  description: The start date of the period for which you want to
                    download a report (ISO 8601 format, e.g., 2025-05-01T00:00:00Z).
                    (RFC 3339 format)
                  format: date-time
                  example: "2022-03-22T12:34:56.123456Z"
                  nullable: true
                type:
                  type: string
                  description: Type of report to download (e.g., monthly). Defaults
                    to monthly.
                  enum:
                  - unknown_report_type
                  - monthly
                  - yearly
                  x-enum-descriptions:
                    values:
                      unknown_report_type: Unknown report type.
                      monthly: Monthly report.
                      yearly: Yearly report.
                  default: unknown_report_type
              required:
              - organization_id
              - date
              x-properties-order:
              - organization_id
              - date
              - type
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"date":"2022-03-22T12:34:56.123456Z","organization_id":"string"}' \
            "https://api.scaleway.com/environmental-footprint/v1alpha1/reports/download"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/environmental-footprint/v1alpha1/reports/download" \
            X-Auth-Token:$SCW_SECRET_KEY \
            date="2022-03-22T12:34:56.123456Z" \
            organization_id="string"
