Get a single entity context

Note: This endpoint is in Preview and is subject to change. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/v2/security_monitoring/entity_context/{id}https://api.ap2.datadoghq.com/api/v2/security_monitoring/entity_context/{id}https://api.datadoghq.eu/api/v2/security_monitoring/entity_context/{id}https://api.ddog-gov.com/api/v2/security_monitoring/entity_context/{id}https://api.us2.ddog-gov.com/api/v2/security_monitoring/entity_context/{id}https://api.uk1.datadoghq.com/api/v2/security_monitoring/entity_context/{id}https://api.datadoghq.com/api/v2/security_monitoring/entity_context/{id}https://api.us3.datadoghq.com/api/v2/security_monitoring/entity_context/{id}https://api.us5.datadoghq.com/api/v2/security_monitoring/entity_context/{id}

Descripción general

Get a single entity from the Cloud SIEM entity context store by its identifier, returning the historical revisions of the entity in the requested time range. The endpoint can either return revisions across an interval (from / to) or the snapshot of the entity at a single point in time (as_of); the two modes are mutually exclusive. This endpoint requires the siem_entities_read permission.

OAuth apps require the siem_entities_read authorization scope to access this endpoint.

Argumentos

Parámetros de ruta

Nombre

Type

Descripción

id [required]

string

The unique identifier of the entity to retrieve.

Cadenas de consulta

Nombre

Type

Descripción

entity_type

enum

The type of entity to retrieve. Only siem_entity_identity is currently supported. Defaults to siem_entity_identity.
Allowed enum values: siem_entity_identity

from

string

The start of the time range to query, as an RFC3339 timestamp or a relative time (for example, now-7d). Defaults to now-7d. Ignored when as_of is set.

to

string

The end of the time range to query, as an RFC3339 timestamp or a relative time (for example, now). Defaults to now. Ignored when as_of is set.

as_of

string

A point in time at which to query the entity revisions, as an RFC3339 timestamp, a Unix timestamp (in seconds), or a relative time (for example, now-1d). When set, from and to are ignored. Cannot be combined with custom from / to values.

Respuesta

OK

Response from the single entity context endpoint, containing the matching entity.

Expand All

Campo

Type

Descripción

data [required]

object

A single entity returned by the entity context endpoint.

attributes [required]

object

The attributes of an entity context entry, grouping all the historical revisions of the entity.

revisions [required]

[object]

The historical revisions of the entity, ordered chronologically.

attributes [required]

object

The set of attributes recorded for the entity at this revision. The keys depend on the kind of entity.

first_seen_at [required]

date-time

The first time the entity was observed at this revision.

last_seen_at [required]

date-time

The last time the entity was observed at this revision.

id [required]

string

The unique identifier of the entity.

type [required]

string

The type of the entity. Reflects the underlying entity kind from the entity context store (for example, siem_entity_identity for identities). Defaults to entity when the kind is unknown.

default: entity

{
  "data": {
    "attributes": {
      "revisions": [
        {
          "attributes": {
            "accounts": [
              "linked-account-123"
            ],
            "display_name": "Test User",
            "email": "user@example.com",
            "principal_id": "user@example.com"
          },
          "first_seen_at": "2026-04-01T00:00:00Z",
          "last_seen_at": "2026-05-01T00:00:00Z"
        }
      ]
    },
    "id": "user@example.com",
    "type": "siem_entity_identity"
  }
}

Bad Request

API error response.

Expand All

Campo

Type

Descripción

errors [required]

[string]

A list of errors.

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

Not Authorized

API error response.

Expand All

Campo

Type

Descripción

errors [required]

[string]

A list of errors.

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

Not Found

API error response.

Expand All

Campo

Type

Descripción

errors [required]

[string]

A list of errors.

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

Too many requests

API error response.

Expand All

Campo

Type

Descripción

errors [required]

[string]

A list of errors.

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

Ejemplo de código

                  # Path parameters
export id="user@example.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# 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.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security_monitoring/entity_context/${id}" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}"
"""
Get a single entity context returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi

configuration = Configuration()
configuration.access_token = environ["DD_BEARER_TOKEN"]
configuration.unstable_operations["get_single_entity_context"] = True
with ApiClient(configuration) as api_client:
    api_instance = SecurityMonitoringApi(api_client)
    response = api_instance.get_single_entity_context(
        id="user@example.com",
    )

    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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" python3 "example.py"
# Get a single entity context returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.access_token = ENV["DD_BEARER_TOKEN"]
  config.unstable_operations["v2.get_single_entity_context".to_sym] = true
end
api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
p api_instance.get_single_entity_context("user@example.com")

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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" rb "example.rb"
// Get a single entity context returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"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())
	ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN"))
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.GetSingleEntityContext", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewSecurityMonitoringApi(apiClient)
	resp, r, err := api.GetSingleEntityContext(ctx, "user@example.com", *datadogV2.NewGetSingleEntityContextOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.GetSingleEntityContext`:\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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" go run "main.go"
// Get a single entity context returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.SecurityMonitoringApi;
import com.datadog.api.client.v2.model.SingleEntityContextResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
    defaultClient.setUnstableOperationEnabled("v2.getSingleEntityContext", true);
    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);

    try {
      SingleEntityContextResponse result = apiInstance.getSingleEntityContext("user@example.com");
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SecurityMonitoringApi#getSingleEntityContext");
      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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" java "Example.java"
// Get a single entity context returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_security_monitoring::GetSingleEntityContextOptionalParams;
use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.get_single_entity_context", true);
    let api = SecurityMonitoringAPI::with_config(configuration);
    let resp = api
        .get_single_entity_context(
            "user@example.com".to_string(),
            GetSingleEntityContextOptionalParams::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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Get a single entity context returns "OK" response
 */

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

const configuration = client.createConfiguration({
  authMethods: {
    AuthZ: {
      accessToken: process.env.DD_BEARER_TOKEN as string,
    },
  },
});
configuration.unstableOperations["v2.getSingleEntityContext"] = true;
const apiInstance = new v2.SecurityMonitoringApi(configuration);

const params: v2.SecurityMonitoringApiGetSingleEntityContextRequest = {
  id: "user@example.com",
};

apiInstance
  .getSingleEntityContext(params)
  .then((data: v2.SingleEntityContextResponse) => {
    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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" tsc "example.ts"