Get an annotated queue interaction

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/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.ap2.datadoghq.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.datadoghq.eu/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.ddog-gov.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.us2.ddog-gov.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.uk1.datadoghq.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.datadoghq.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.us3.datadoghq.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}https://api.us5.datadoghq.com/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}

Overview

Retrieve an interaction, its annotations, and a page of related events from an annotation queue.

Arguments

Path Parameters

Name

Type

Description

queue_id [required]

string

The ID of the Agent Observability annotation queue.

interaction_id [required]

string

The ID of the interaction in the annotation queue.

Query Strings

Name

Type

Description

limit

integer

Maximum number of events to return. Defaults to 10.

cursor

string

Cursor from the previous response to retrieve the next page of events.

Response

OK

Response containing a single annotated interaction and its related events.

Expand All

Field

Type

Description

data [required]

object

Data object for a single annotated interaction.

attributes [required]

object

Attributes containing an annotated interaction and its related events.

annotated_interaction [required]

 <oneOf>

An interaction with its associated annotations.

Object 1

object

A trace, experiment trace, or session interaction with its associated annotations.

annotations [required]

[object]

List of annotations for this interaction.

created_at [required]

date-time

Timestamp when the annotation was created.

created_by [required]

string

Identifier of the user who created the annotation.

id [required]

string

Unique identifier of the annotation.

interaction_id [required]

string

Identifier of the interaction this annotation belongs to.

label_values [required]

object

Label values for this annotation.

modified_at [required]

date-time

Timestamp when the annotation was last modified.

modified_by [required]

string

Identifier of the user who last modified the annotation.

can_annotate [required]

boolean

Whether the current caller can annotate this interaction.

content_id [required]

string

Upstream entity identifier supplied by the caller.

created_at [required]

date-time

Timestamp when the interaction was added to the queue.

id [required]

string

Unique identifier of the interaction.

modified_at [required]

date-time

Timestamp when the interaction was last updated.

type [required]

enum

Type of an upstream-entity interaction. Allowed enum values: trace,experiment_trace,session

<type=display_block>

object

A display_block interaction with its associated annotations.

annotations [required]

[object]

List of annotations for this interaction.

created_at [required]

date-time

Timestamp when the annotation was created.

created_by [required]

string

Identifier of the user who created the annotation.

id [required]

string

Unique identifier of the annotation.

interaction_id [required]

string

Identifier of the interaction this annotation belongs to.

label_values [required]

object

Label values for this annotation.

modified_at [required]

date-time

Timestamp when the annotation was last modified.

modified_by [required]

string

Identifier of the user who last modified the annotation.

can_annotate [required]

boolean

Whether the current caller can annotate this interaction.

content_id [required]

string

Server-generated deterministic identifier derived from the block list.

display_block [required]

[object]

List of content blocks that make up a display_block interaction. Must contain at least one block.

alt

string

Alternative text for an image block.

code

string

HTML code rendered by a frontend block. Required for frontend blocks.

content

Block payload. A string for markdown, header, and text; an arbitrary JSON value (object, array, or scalar) for json. Omitted for image, widget, llmobs_trace, and frontend.

height

int64

Optional rendered height. Must be positive when set.

interactionType

enum

Upstream interaction type referenced by an llmobs_trace block. Restricted to trace or experiment_trace. Allowed enum values: trace,experiment_trace

label

string

Optional label rendered alongside a frontend block.

level

enum

Visual size for a header block. Allowed enum values: sm,md,lg,xl

tileDef

Tile definition for a widget block. Required for widget. The schema is owned by the frontend renderer.

timeFrame

object

Unix-millis time range used by chart blocks.

end [required]

int64

End of the range, in Unix milliseconds.

start [required]

int64

Start of the range, in Unix milliseconds.

traceId

string

Trace identifier. Required for llmobs_trace blocks.

type [required]

enum

Discriminator for a single display_block content block. Adding a variant requires coordinated changes in the frontend renderer. Allowed enum values: markdown,header,text,json,image,widget,llmobs_trace,frontend

url

string

URL of the image. Required for image blocks.

id [required]

string

Unique identifier of the interaction.

type [required]

enum

Type discriminator for a display_block interaction. Allowed enum values: display_block

events [required]

[object]

Page of events associated with the annotated interaction.

attributes [required]

object

Attributes of an event associated with an annotated interaction.

id [required]

string

Unique identifier of the event.

type [required]

string

Type of the event.

interaction_type [required]

enum

Type of an annotated interaction. Allowed enum values: trace,experiment_trace,session,display_block

next_cursor

string

Cursor to retrieve the next page of events. Absent when there are no more events.

id [required]

string

Unique identifier of the interaction.

type [required]

enum

Resource type for annotated interactions. Allowed enum values: annotated_interactions

{
  "data": {
    "attributes": {
      "annotated_interaction": {
        "annotations": [
          {
            "created_at": "2024-01-15T10:30:00Z",
            "created_by": "00000000-0000-0000-0000-000000000002",
            "id": "annotation-789",
            "interaction_id": "interaction-456",
            "label_values": [
              {}
            ],
            "modified_at": "2024-01-15T10:30:00Z",
            "modified_by": "00000000-0000-0000-0000-000000000002"
          }
        ],
        "can_annotate": true,
        "content_id": "trace-abc-123",
        "created_at": "2024-01-15T10:30:00Z",
        "id": "interaction-456",
        "modified_at": "2024-01-15T10:30:00Z",
        "type": "trace"
      },
      "events": [
        {
          "attributes": {
            "duration": 1500000000,
            "ml_app": "my-llm-app",
            "name": "agent_workflow",
            "span_id": "span-7a1b2c3d",
            "span_kind": "agent",
            "start_ns": 1705314600000000000,
            "status": "ok",
            "trace_id": "trace-abc-123"
          },
          "id": "span-7a1b2c3d",
          "type": "span"
        }
      ],
      "interaction_type": "trace",
      "next_cursor": "eyJzdGFydCI6MTAwfQ=="
    },
    "id": "interaction-456",
    "type": "annotated_interactions"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "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

                  # Path parameters
export queue_id="00000000-0000-0000-0000-000000000001"
export interaction_id="interaction-456"
# 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/llm-obs/v1/annotation-queues/${queue_id}/annotated-interactions/${interaction_id}" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}"
"""
Get an annotated queue interaction returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.agent_observability_api import AgentObservabilityApi

configuration = Configuration()
configuration.access_token = environ["DD_BEARER_TOKEN"]
configuration.unstable_operations["get_llm_obs_annotated_interaction"] = True
with ApiClient(configuration) as api_client:
    api_instance = AgentObservabilityApi(api_client)
    response = api_instance.get_llm_obs_annotated_interaction(
        queue_id="queue_id",
        interaction_id="interaction_id",
    )

    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 an annotated queue interaction returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.access_token = ENV["DD_BEARER_TOKEN"]
  config.unstable_operations["v2.get_llm_obs_annotated_interaction".to_sym] = true
end
api_instance = DatadogAPIClient::V2::AgentObservabilityAPI.new
p api_instance.get_llm_obs_annotated_interaction("queue_id", "interaction_id")

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 an annotated queue interaction 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.GetLLMObsAnnotatedInteraction", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewAgentObservabilityApi(apiClient)
	resp, r, err := api.GetLLMObsAnnotatedInteraction(ctx, "queue_id", "interaction_id", *datadogV2.NewGetLLMObsAnnotatedInteractionOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `AgentObservabilityApi.GetLLMObsAnnotatedInteraction`:\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 an annotated queue interaction returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.AgentObservabilityApi;
import com.datadog.api.client.v2.model.LLMObsAnnotatedInteractionResponse;

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

    try {
      LLMObsAnnotatedInteractionResponse result =
          apiInstance.getLLMObsAnnotatedInteraction(
              "00000000-0000-0000-0000-000000000001", "interaction-456");
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println(
          "Exception when calling AgentObservabilityApi#getLLMObsAnnotatedInteraction");
      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 an annotated queue interaction returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_agent_observability::AgentObservabilityAPI;
use datadog_api_client::datadogV2::api_agent_observability::GetLLMObsAnnotatedInteractionOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.GetLLMObsAnnotatedInteraction", true);
    let api = AgentObservabilityAPI::with_config(configuration);
    let resp = api
        .get_llm_obs_annotated_interaction(
            "queue_id".to_string(),
            "interaction_id".to_string(),
            GetLLMObsAnnotatedInteractionOptionalParams::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 an annotated queue interaction 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.getLLMObsAnnotatedInteraction"] = true;
const apiInstance = new v2.AgentObservabilityApi(configuration);

const params: v2.AgentObservabilityApiGetLLMObsAnnotatedInteractionRequest = {
  queueId: "queue_id",
  interactionId: "interaction_id",
};

apiInstance
  .getLLMObsAnnotatedInteraction(params)
  .then((data: v2.LLMObsAnnotatedInteractionResponse) => {
    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"