Submit distribution points

POST https://api.ap1.datadoghq.com/api/v1/distribution_pointshttps://api.ap2.datadoghq.com/api/v1/distribution_pointshttps://api.datadoghq.eu/api/v1/distribution_pointshttps://api.ddog-gov.com/api/v1/distribution_pointshttps://api.us2.ddog-gov.com/api/v1/distribution_pointshttps://api.datadoghq.com/api/v1/distribution_pointshttps://api.us3.datadoghq.com/api/v1/distribution_pointshttps://api.us5.datadoghq.com/api/v1/distribution_points

Overview

The distribution points end-point allows you to post distribution data that can be graphed on Datadog’s dashboards.

Arguments

Header Parameters

Name

Type

Description

Content-Encoding

string

HTTP header used to compress the media-type.

Request

Body Data (required)

Expand All

Field

Type

Description

series [required]

[object]

A list of distribution points series to submit to Datadog.

host

string

The name of the host that produced the distribution point metric.

metric [required]

string

The name of the distribution points metric.

points [required]

[array]

Points relating to the distribution point metric. All points must be tuples with timestamp and a list of values (cannot be a string). Timestamps should be in POSIX time in seconds.

tags

[string]

A list of tags associated with the distribution point metric.

type

enum

The type of the distribution point. Allowed enum values: distribution

default: distribution

{
  "series": [
    {
      "metric": "system.load.1.dist",
      "points": [
        [
          1636629071,
          [
            1.0,
            2.0
          ]
        ]
      ]
    }
  ]
}
{
  "series": [
    {
      "metric": "system.load.1.dist",
      "points": [
        [
          1636629071,
          [
            1.0,
            2.0
          ]
        ]
      ]
    }
  ]
}

Response

Payload accepted

The payload accepted for intake.

Expand All

Field

Type

Description

status

string

The status of the intake payload.

{
  "status": "ok"
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Authentication error

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Request timeout

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Payload too large

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Too many requests

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

                          ## default
# 

See one of the other client libraries for an example of sending deflate-compressed data.

## Dynamic Points # Post time-series data that can be graphed on Datadog’s dashboards.
See one of the other client libraries for an example of sending deflate-compressed data.

                          ## default
# 

# Curl command
curl -X POST "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/v1/distribution_points" \ -H "Accept: application/json" \ -H "Content-Type: text/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -d @- << EOF { "series": [ { "host": "test.example.com", "metric": "system.load.1", "points": [ [ 1636629071, [ 1, 2 ] ] ], "tags": [ "environment:test" ], "type": "distribution" } ] } EOF
## Dynamic Points # Post time-series data that can be graphed on Datadog’s dashboards.
# Template variables
export NOW="$(date +%s)"
# Curl command
curl -X POST "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/v1/distribution_points" \ -H "Accept: application/json" \ -H "Content-Type: text/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -d @- << EOF { "series": [ { "metric": "system.load.1.dist", "points": [[${NOW}, [1234.5]]] } ] } EOF
// Submit deflate distribution points returns "Payload accepted" 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/datadogV1"
)

func main() {
	body := datadogV1.DistributionPointsPayload{
		Series: []datadogV1.DistributionPointsSeries{
			{
				Metric: "system.load.1.dist",
				Points: [][]datadogV1.DistributionPointItem{
					{
						{DistributionPointTimestamp: datadog.PtrFloat64(float64(time.Now().Unix()))},
						{DistributionPointData: &[]float64{
							1.0,
							2.0,
						}},
					},
				},
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV1.NewMetricsApi(apiClient)
	resp, r, err := api.SubmitDistributionPoints(ctx, body, *datadogV1.NewSubmitDistributionPointsOptionalParameters().WithContentEncoding(datadogV1.DISTRIBUTIONPOINTSCONTENTENCODING_DEFLATE))

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.SubmitDistributionPoints`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `MetricsApi.SubmitDistributionPoints`:\n%s\n", responseContent)
}
// Submit distribution points returns "Payload accepted" 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/datadogV1"
)

func main() {
	body := datadogV1.DistributionPointsPayload{
		Series: []datadogV1.DistributionPointsSeries{
			{
				Metric: "system.load.1.dist",
				Points: [][]datadogV1.DistributionPointItem{
					{
						{DistributionPointTimestamp: datadog.PtrFloat64(float64(time.Now().Unix()))},
						{DistributionPointData: &[]float64{
							1.0,
							2.0,
						}},
					},
				},
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV1.NewMetricsApi(apiClient)
	resp, r, err := api.SubmitDistributionPoints(ctx, body, *datadogV1.NewSubmitDistributionPointsOptionalParameters())

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.SubmitDistributionPoints`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `MetricsApi.SubmitDistributionPoints`:\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>" go run "main.go"
// Submit deflate distribution points returns "Payload accepted" response
import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v1.api.MetricsApi;
import com.datadog.api.client.v1.api.MetricsApi.SubmitDistributionPointsOptionalParameters;
import com.datadog.api.client.v1.model.DistributionPointItem;
import com.datadog.api.client.v1.model.DistributionPointsContentEncoding;
import com.datadog.api.client.v1.model.DistributionPointsPayload;
import com.datadog.api.client.v1.model.DistributionPointsSeries;
import com.datadog.api.client.v1.model.IntakePayloadAccepted;
import java.time.OffsetDateTime;
import java.util.Arrays;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    MetricsApi apiInstance = new MetricsApi(defaultClient);

    DistributionPointsPayload body =
        new DistributionPointsPayload()
            .series(
                Collections.singletonList(
                    new DistributionPointsSeries()
                        .metric("system.load.1.dist")
                        .points(
                            Collections.singletonList(
                                Arrays.asList(
                                    new DistributionPointItem(
                                        Long.valueOf(
                                                OffsetDateTime.now().toInstant().getEpochSecond())
                                            .doubleValue()),
                                    new DistributionPointItem(Arrays.asList(1.0, 2.0)))))));

    try {
      IntakePayloadAccepted result =
          apiInstance.submitDistributionPoints(
              body,
              new SubmitDistributionPointsOptionalParameters()
                  .contentEncoding(DistributionPointsContentEncoding.DEFLATE));
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling MetricsApi#submitDistributionPoints");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}
// Submit distribution points returns "Payload accepted" response
import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v1.api.MetricsApi;
import com.datadog.api.client.v1.model.DistributionPointItem;
import com.datadog.api.client.v1.model.DistributionPointsPayload;
import com.datadog.api.client.v1.model.DistributionPointsSeries;
import com.datadog.api.client.v1.model.IntakePayloadAccepted;
import java.time.OffsetDateTime;
import java.util.Arrays;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    MetricsApi apiInstance = new MetricsApi(defaultClient);

    DistributionPointsPayload body =
        new DistributionPointsPayload()
            .series(
                Collections.singletonList(
                    new DistributionPointsSeries()
                        .metric("system.load.1.dist")
                        .points(
                            Collections.singletonList(
                                Arrays.asList(
                                    new DistributionPointItem(
                                        Long.valueOf(
                                                OffsetDateTime.now().toInstant().getEpochSecond())
                                            .doubleValue()),
                                    new DistributionPointItem(Arrays.asList(1.0, 2.0)))))));

    try {
      IntakePayloadAccepted result = apiInstance.submitDistributionPoints(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling MetricsApi#submitDistributionPoints");
      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>" java "Example.java"
"""
Submit deflate distribution points returns "Payload accepted" response
"""

from datetime import datetime
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.metrics_api import MetricsApi
from datadog_api_client.v1.model.distribution_point import DistributionPoint
from datadog_api_client.v1.model.distribution_points_content_encoding import DistributionPointsContentEncoding
from datadog_api_client.v1.model.distribution_points_payload import DistributionPointsPayload
from datadog_api_client.v1.model.distribution_points_series import DistributionPointsSeries

body = DistributionPointsPayload(
    series=[
        DistributionPointsSeries(
            metric="system.load.1.dist",
            points=[
                DistributionPoint(
                    [
                        datetime.now().timestamp(),
                        [1.0, 2.0],
                    ]
                ),
            ],
        ),
    ],
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = MetricsApi(api_client)
    response = api_instance.submit_distribution_points(
        content_encoding=DistributionPointsContentEncoding.DEFLATE, body=body
    )

    print(response)
"""
Submit distribution points returns "Payload accepted" response
"""

from datetime import datetime
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.metrics_api import MetricsApi
from datadog_api_client.v1.model.distribution_point import DistributionPoint
from datadog_api_client.v1.model.distribution_points_payload import DistributionPointsPayload
from datadog_api_client.v1.model.distribution_points_series import DistributionPointsSeries

body = DistributionPointsPayload(
    series=[
        DistributionPointsSeries(
            metric="system.load.1.dist",
            points=[
                DistributionPoint(
                    [
                        datetime.now().timestamp(),
                        [1.0, 2.0],
                    ]
                ),
            ],
        ),
    ],
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = MetricsApi(api_client)
    response = api_instance.submit_distribution_points(body=body)

    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>" python3 "example.py"
# Submit deflate distribution points returns "Payload accepted" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V1::MetricsAPI.new

body = DatadogAPIClient::V1::DistributionPointsPayload.new({
  series: [
    DatadogAPIClient::V1::DistributionPointsSeries.new({
      metric: "system.load.1.dist",
      points: [
        [
          Time.now,
          [
            1.0,
            2.0,
          ],
        ],
      ],
    }),
  ],
})
opts = {
  content_encoding: DistributionPointsContentEncoding::DEFLATE,
}
p api_instance.submit_distribution_points(body, opts)
# Submit distribution points returns "Payload accepted" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V1::MetricsAPI.new

body = DatadogAPIClient::V1::DistributionPointsPayload.new({
  series: [
    DatadogAPIClient::V1::DistributionPointsSeries.new({
      metric: "system.load.1.dist",
      points: [
        [
          Time.now,
          [
            1.0,
            2.0,
          ],
        ],
      ],
    }),
  ],
})
p api_instance.submit_distribution_points(body)

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>" rb "example.rb"
// Submit deflate distribution points returns "Payload accepted" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV1::api_metrics::MetricsAPI;
use datadog_api_client::datadogV1::api_metrics::SubmitDistributionPointsOptionalParams;
use datadog_api_client::datadogV1::model::DistributionPointItem;
use datadog_api_client::datadogV1::model::DistributionPointsContentEncoding;
use datadog_api_client::datadogV1::model::DistributionPointsPayload;
use datadog_api_client::datadogV1::model::DistributionPointsSeries;

#[tokio::main]
async fn main() {
    let body = DistributionPointsPayload::new(vec![DistributionPointsSeries::new(
        "system.load.1.dist".to_string(),
        vec![vec![
            DistributionPointItem::DistributionPointTimestamp(1636629071.0 as f64),
            DistributionPointItem::DistributionPointData(vec![1.0, 2.0]),
        ]],
    )]);
    let configuration = datadog::Configuration::new();
    let api = MetricsAPI::with_config(configuration);
    let resp = api
        .submit_distribution_points(
            body,
            SubmitDistributionPointsOptionalParams::default()
                .content_encoding(DistributionPointsContentEncoding::DEFLATE),
        )
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}
// Submit distribution points returns "Payload accepted" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV1::api_metrics::MetricsAPI;
use datadog_api_client::datadogV1::api_metrics::SubmitDistributionPointsOptionalParams;
use datadog_api_client::datadogV1::model::DistributionPointItem;
use datadog_api_client::datadogV1::model::DistributionPointsPayload;
use datadog_api_client::datadogV1::model::DistributionPointsSeries;

#[tokio::main]
async fn main() {
    let body = DistributionPointsPayload::new(vec![DistributionPointsSeries::new(
        "system.load.1.dist".to_string(),
        vec![vec![
            DistributionPointItem::DistributionPointTimestamp(1636629071.0 as f64),
            DistributionPointItem::DistributionPointData(vec![1.0, 2.0]),
        ]],
    )]);
    let configuration = datadog::Configuration::new();
    let api = MetricsAPI::with_config(configuration);
    let resp = api
        .submit_distribution_points(body, SubmitDistributionPointsOptionalParams::default())
        .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>" cargo run
/**
 * Submit deflate distribution points returns "Payload accepted" response
 */

import { client, v1 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v1.MetricsApi(configuration);

const params: v1.MetricsApiSubmitDistributionPointsRequest = {
  body: {
    series: [
      {
        metric: "system.load.1.dist",
        points: [[Math.round(new Date().getTime() / 1000), [1.0, 2.0]]],
      },
    ],
  },
  contentEncoding: "deflate",
};

apiInstance
  .submitDistributionPoints(params)
  .then((data: v1.IntakePayloadAccepted) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));
/**
 * Submit distribution points returns "Payload accepted" response
 */

import { client, v1 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v1.MetricsApi(configuration);

const params: v1.MetricsApiSubmitDistributionPointsRequest = {
  body: {
    series: [
      {
        metric: "system.load.1.dist",
        points: [[Math.round(new Date().getTime() / 1000), [1.0, 2.0]]],
      },
    ],
  },
};

apiInstance
  .submitDistributionPoints(params)
  .then((data: v1.IntakePayloadAccepted) => {
    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>" tsc "example.ts"