Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED US2-FED

Get annotated interactions by content IDs

copy Copy pageCopied

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/annotated-interactionshttps://api.ap2.datadoghq.com/api/v2/llm-obs/v1/annotated-interactionshttps://api.datadoghq.eu/api/v2/llm-obs/v1/annotated-interactionshttps://api.ddog-gov.com/api/v2/llm-obs/v1/annotated-interactionshttps://api.us2.ddog-gov.com/api/v2/llm-obs/v1/annotated-interactionshttps://api.datadoghq.com/api/v2/llm-obs/v1/annotated-interactionshttps://api.us3.datadoghq.com/api/v2/llm-obs/v1/annotated-interactionshttps://api.us5.datadoghq.com/api/v2/llm-obs/v1/annotated-interactions

Overview

Returns annotated interactions across all annotation queues for the given content IDs. Results include queue metadata (ID and name) for each interaction.

Arguments

Query Strings

Name

Type

Description

contentIds [required]

array

One or more content IDs to retrieve annotated interactions for. At least one is required.

offset

integer

Pagination offset. Must be >= 0. Defaults to 0.

limit

integer

Maximum number of results to return. Must be > 0. Defaults to 100.

Response

OK

Response containing annotated interactions across all queues for the requested content IDs.

Expand All

Field

Type

Description

data [required]

object

Data object for the cross-queue annotated interactions response.

attributes [required]

object

Attributes of the cross-queue annotated interactions response.

annotated_interactions [required]

[object]

List of annotated interactions across all queues for the requested content IDs.

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.

content_id [required]

string

Upstream entity identifier (trace ID, session ID, or deterministic display_block ID).

created_at [required]

date-time

Timestamp when the interaction was added to the queue.

display_block

[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.

content

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

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 the 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

url

string

URL of the image. Required for image blocks.

id [required]

string

Unique identifier of the interaction.

modified_at [required]

date-time

Timestamp when the interaction was last updated.

queue_id [required]

string

Identifier of the annotation queue this interaction belongs to.

queue_name [required]

string

Name of the annotation queue this interaction belongs to.

type [required]

enum

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

total_count [required]

int32

Total number of annotated interactions matching the query.

id [required]

string

Opaque identifier for the response object.

type [required]

enum

Resource type for cross-queue annotated interactions lookup. Allowed enum values: annotated_interactions_by_trace

{
  "data": {
    "attributes": {
      "annotated_interactions": [
        {
          "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"
            }
          ],
          "content_id": "trace-abc-123",
          "created_at": "2025-06-01T12:00:00Z",
          "display_block": [
            {
              "alt": "Example image",
              "content": "## Triage Instructions",
              "height": 240,
              "interactionType": "trace",
              "label": "Triage Instructions",
              "level": "md",
              "tileDef": {
                "requests": [
                  {
                    "queries": [
                      {
                        "data_source": "metrics",
                        "name": "q",
                        "query": "avg:system.cpu.user{*}"
                      }
                    ],
                    "response_format": "timeseries",
                    "type": "line"
                  }
                ],
                "viz": "timeseries"
              },
              "timeFrame": {
                "end": 1705315800000,
                "start": 1705312200000
              },
              "traceId": "69fcc2bb0000000003113989d83069ba",
              "type": "markdown",
              "url": "https://example.com/image.png"
            }
          ],
          "id": "interaction-456",
          "modified_at": "2025-06-01T12:00:00Z",
          "queue_id": "queue-uuid-001",
          "queue_name": "My Annotation Queue",
          "type": "trace"
        }
      ],
      "total_count": 1
    },
    "id": "trace-query",
    "type": "annotated_interactions_by_trace"
  }
}

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"
    }
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Internal Server Error

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"
    }
  ]
}

Code Example

                  # Required query arguments
export contentIds="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/llm-obs/v1/annotated-interactions?contentIds=${contentIds}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"