For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/agent-observability/list-agent-observability-spans.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

List Agent Observability spans

WARNINGNote: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.
GEThttps://api.datadoghq.com/api/v2/llm-obs/v1/spans/eventshttps://api.us3.datadoghq.com/api/v2/llm-obs/v1/spans/eventshttps://api.us5.datadoghq.com/api/v2/llm-obs/v1/spans/eventshttps://api.datadoghq.eu/api/v2/llm-obs/v1/spans/eventshttps://api.ap1.datadoghq.com/api/v2/llm-obs/v1/spans/eventshttps://api.ap2.datadoghq.com/api/v2/llm-obs/v1/spans/eventshttps://api.uk1.datadoghq.com/api/v2/llm-obs/v1/spans/eventshttps://api.ddog-gov.com/api/v2/llm-obs/v1/spans/eventshttps://api.us2.ddog-gov.com/api/v2/llm-obs/v1/spans/events

Overview

List Agent Observability spans matching the specified filters.

Arguments

Query Strings

Name
Type
Description
filter[from]
string

Start of the time range. Accepts ISO 8601 or relative format (e.g., now-15m). Defaults to now-15m.

filter[to]
string

End of the time range. Accepts ISO 8601 or relative format. Defaults to now.

filter[query]
string

Search query using Agent Observability query syntax. Supports attribute filters using the field:value syntax (e.g. session_id, trace_id, ml_app, meta.span.kind). When provided, structured field filters (filter[span_id], filter[trace_id], etc.) are ignored.

filter[span_id]
string

Filter by exact span ID.

filter[trace_id]
string

Filter by exact trace ID.

filter[span_kind]
string

Filter by span kind (e.g., llm, agent, tool, task, workflow).

filter[span_name]
string

Filter by span name.

filter[ml_app]
string

Filter by ML application name.

page[limit]
integer

Maximum number of spans to return. Defaults to 10.

page[cursor]
string

Cursor from the previous response to retrieve the next page.

sort
string

Sort order for the results.

include_attachments
boolean

Whether to include attachment data in the response. Defaults to true.

Response

OK

Response containing a list of Agent Observability spans.

Field
Type
Description
data [required]
[object]

List of spans matching the query.

links
object

Pagination links accompanying the spans response.

meta [required]
object

Metadata accompanying the spans response.

Code Example

List Agent Observability spans
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/llm-obs/v1/spans/events" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"