Get historical cost across your account

GET https://api.ap1.datadoghq.com/api/v2/usage/historical_costhttps://api.ap2.datadoghq.com/api/v2/usage/historical_costhttps://api.datadoghq.eu/api/v2/usage/historical_costhttps://api.ddog-gov.com/api/v2/usage/historical_costhttps://api.us2.ddog-gov.com/api/v2/usage/historical_costhttps://api.datadoghq.com/api/v2/usage/historical_costhttps://api.us3.datadoghq.com/api/v2/usage/historical_costhttps://api.us5.datadoghq.com/api/v2/usage/historical_cost

Overview

Get historical cost across multi-org and single root-org accounts. Cost data for a given month becomes available no later than the 16th of the following month.

This endpoint is only accessible for parent-level organizations.

This endpoint requires all of the following permissions:
  • usage_read
  • billing_read

  • OAuth apps require the usage_read, billing_read authorization scope to access this endpoint.

    Arguments

    Query Strings

    Name

    Type

    Description

    start_month [required]

    string

    Datetime in ISO-8601 format, UTC, precise to month: [YYYY-MM] for cost beginning this month.

    view

    string

    String to specify whether cost is broken down at a parent-org level or at the sub-org level. Available views are summary and sub-org. Defaults to summary.

    end_month

    string

    Datetime in ISO-8601 format, UTC, precise to month: [YYYY-MM] for cost ending this month.

    include_connected_accounts

    boolean

    Boolean to specify whether to include accounts connected to the current account as partner customers in the Datadog partner network program. Defaults to false.

    Response

    OK

    Chargeback Summary response.

    Expand All

    Field

    Type

    Description

    data

    [object]

    Response containing Chargeback Summary.

    attributes

    object

    Cost attributes data.

    account_name

    string

    The account name.

    account_public_id

    string

    The account public ID.

    charges

    [object]

    List of charges data reported for the requested month.

    charge_type

    string

    The type of charge for a particular product.

    cost

    double

    The cost for a particular product and charge type during a given month.

    product_name

    string

    The product for which cost is being reported.

    date

    date-time

    The month requested.

    org_name

    string

    The organization name.

    public_id

    string

    The organization public ID.

    region

    string

    The region of the Datadog instance that the organization belongs to.

    total_cost

    double

    The total cost of products for the month.

    id

    string

    Unique ID of the response.

    type

    enum

    Type of cost data. Allowed enum values: cost_by_org

    default: cost_by_org

    {
      "data": [
        {
          "attributes": {
            "account_name": "string",
            "account_public_id": "string",
            "charges": [
              {
                "charge_type": "on_demand",
                "cost": "number",
                "product_name": "infra_host"
              }
            ],
            "date": "2019-09-19T10:00:00.000Z",
            "org_name": "string",
            "public_id": "string",
            "region": "string",
            "total_cost": "number"
          },
          "id": "string",
          "type": "cost_by_org"
        }
      ]
    }

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Forbidden - User is not authorized

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Code Example

                      # Required query arguments
    export start_month="CHANGE_ME"
    # Curl command
    curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/usage/historical_cost?start_month=${start_month}" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
    """
    Get historical cost across your account returns "OK" response
    """
    
    from datetime import datetime
    from dateutil.relativedelta import relativedelta
    from datadog_api_client import ApiClient, Configuration
    from datadog_api_client.v2.api.usage_metering_api import UsageMeteringApi
    
    configuration = Configuration()
    with ApiClient(configuration) as api_client:
        api_instance = UsageMeteringApi(api_client)
        response = api_instance.get_historical_cost_by_org(
            start_month=(datetime.now() + relativedelta(months=-2)),
            view="sub-org",
        )
    
        print(response)
    

    Instructions

    First install the library and its dependencies and then save the example to example.py and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
    # Get historical cost across your account returns "OK" response
    
    require "datadog_api_client"
    api_instance = DatadogAPIClient::V2::UsageMeteringAPI.new
    opts = {
      view: "sub-org",
    }
    p api_instance.get_historical_cost_by_org((Time.now + -2 * 86400 * 30), opts)
    

    Instructions

    First install the library and its dependencies and then save the example to example.rb and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
    // Get historical cost across your account returns "OK" response
    
    package main
    
    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"os"
    	"time"
    
    	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
    	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
    )
    
    func main() {
    	ctx := datadog.NewDefaultContext(context.Background())
    	configuration := datadog.NewConfiguration()
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewUsageMeteringApi(apiClient)
    	resp, r, err := api.GetHistoricalCostByOrg(ctx, time.Now().AddDate(0, -2, 0), *datadogV2.NewGetHistoricalCostByOrgOptionalParameters().WithView("sub-org"))
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `UsageMeteringApi.GetHistoricalCostByOrg`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `UsageMeteringApi.GetHistoricalCostByOrg`:\n%s\n", responseContent)
    }
    

    Instructions

    First install the library and its dependencies and then save the example to main.go and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
    // Get historical cost across your account returns "OK" response
    import com.datadog.api.client.ApiClient;
    import com.datadog.api.client.ApiException;
    import com.datadog.api.client.v2.api.UsageMeteringApi;
    import com.datadog.api.client.v2.api.UsageMeteringApi.GetHistoricalCostByOrgOptionalParameters;
    import com.datadog.api.client.v2.model.CostByOrgResponse;
    import java.time.OffsetDateTime;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        UsageMeteringApi apiInstance = new UsageMeteringApi(defaultClient);
    
        try {
          CostByOrgResponse result =
              apiInstance.getHistoricalCostByOrg(
                  OffsetDateTime.now().plusMonths(-2),
                  new GetHistoricalCostByOrgOptionalParameters().view("sub-org"));
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling UsageMeteringApi#getHistoricalCostByOrg");
          System.err.println("Status code: " + e.getCode());
          System.err.println("Reason: " + e.getResponseBody());
          System.err.println("Response headers: " + e.getResponseHeaders());
          e.printStackTrace();
        }
      }
    }
    

    Instructions

    First install the library and its dependencies and then save the example to Example.java and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
    // Get historical cost across your account returns "OK" response
    use chrono::{DateTime, Utc};
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_usage_metering::GetHistoricalCostByOrgOptionalParams;
    use datadog_api_client::datadogV2::api_usage_metering::UsageMeteringAPI;
    
    #[tokio::main]
    async fn main() {
        let configuration = datadog::Configuration::new();
        let api = UsageMeteringAPI::with_config(configuration);
        let resp = api
            .get_historical_cost_by_org(
                DateTime::parse_from_rfc3339("2021-09-11T11:11:11+00:00")
                    .expect("Failed to parse datetime")
                    .with_timezone(&Utc),
                GetHistoricalCostByOrgOptionalParams::default().view("sub-org".to_string()),
            )
            .await;
        if let Ok(value) = resp {
            println!("{:#?}", value);
        } else {
            println!("{:#?}", resp.unwrap_err());
        }
    }
    

    Instructions

    First install the library and its dependencies and then save the example to src/main.rs and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
    /**
     * Get historical cost across your account returns "OK" response
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    const apiInstance = new v2.UsageMeteringApi(configuration);
    
    const params: v2.UsageMeteringApiGetHistoricalCostByOrgRequest = {
      startMonth: new Date(new Date().getTime() + -2 * 86400 * 30 * 1000),
      view: "sub-org",
    };
    
    apiInstance
      .getHistoricalCostByOrg(params)
      .then((data: v2.CostByOrgResponse) => {
        console.log(
          "API called successfully. Returned data: " + JSON.stringify(data)
        );
      })
      .catch((error: any) => console.error(error));
    

    Instructions

    First install the library and its dependencies and then save the example to example.ts and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"