--- title: "Search LLM Observability spans" method: POST path: "/api/v2/llm-obs/v1/spans/events/search" tags: ["LLM Observability"] --- # Search LLM Observability spans `POST /api/v2/llm-obs/v1/spans/events/search` Search LLM Observability spans using structured filters in the request body. ## Request body - LLMObsSearchSpansRequest — Request body for searching LLM Observability spans. - `data` LLMObsSearchSpansRequestData, required — Data object for an LLM Observability spans search request. - `attributes` LLMObsSearchSpansRequestAttributes, required — Attributes of an LLM Observability spans search request. - `filter` LLMObsSpanFilter — Filter criteria for an LLM Observability span search. - `from` string — Start of the time range. Accepts ISO 8601 or relative format (e.g., `now-15m`). Defaults to `now-15m`. - `ml_app` string — Filter by ML application name. - `query` string — Search query using LLM 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 (`span_id`, `trace_id`, etc.) are ignored. - `span_id` string — Filter by exact span ID. - `span_kind` string — Filter by span kind (e.g., llm, agent, tool, task, workflow). - `span_name` string — Filter by span name. - `tags` object — Filter by tag key-value pairs. - `to` string — End of the time range. Accepts ISO 8601 or relative format (e.g., `now`). Defaults to `now`. - `trace_id` string — Filter by exact trace ID. - `options` LLMObsSpanSearchOptions — Additional options for a span search request. - `include_attachments` boolean — Whether to include attachment data in the response. Defaults to `true`. - `time_offset` integer — Offset in seconds applied to both `from` and `to` timestamps. - `page` LLMObsSpanPageQuery — Pagination settings for a span search request. - `cursor` string — Cursor from the previous response to retrieve the next page. - `limit` integer — Maximum number of spans to return. Defaults to `10`. - `sort` string — Sort order for the results. Use `-` prefix for descending order. - `type` 'spans', required — Resource type for an LLM Observability spans search request. ## Response `200` OK - LLMObsSpansResponse — Response containing a list of LLM Observability spans. - `data` LLMObsSpanData[], required — List of spans matching the query. - `attributes` LLMObsSpanAttributes, required — Attributes of an LLM Observability span. - `duration` number, double, required — Duration of the span in nanoseconds. - `evaluation` object — Evaluation metrics keyed by evaluator name. - `input` LLMObsSpanIO — Input or output content of an LLM Observability span. - `messages` LLMObsSpanMessage[] — List of messages in the input or output. - `content` string — Text content of the message. - `id` string — Unique identifier of the message. - `role` string — Role of the message sender (e.g., user, assistant, system). - `tool_calls` LLMObsSpanToolCall[] — Tool calls made in this message. - `arguments` object — Arguments passed to the tool. - `name` string — Name of the tool called. - `tool_id` string — Identifier of the tool call. - `type` string — Type of the tool call. - `tool_results` LLMObsSpanToolResult[] — Tool results returned in this message. - `name` string — Name of the tool that produced this result. - `result` string — Result value returned by the tool. - `tool_id` string — Identifier of the corresponding tool call. - `type` string — Type of the tool result. - `value` string — Plain-text value of the input or output. - `intent` string — Detected intent of the span. - `metadata` object — Arbitrary metadata associated with the span. - `metrics` object — Numeric metrics associated with the span (e.g., token counts). - `ml_app` string, required — Name of the ML application this span belongs to. - `model_name` string — Name of the model used in this span. - `model_provider` string — Provider of the model used in this span. - `name` string, required — Name of the span. - `output` LLMObsSpanIO — Input or output content of an LLM Observability span. - `messages` LLMObsSpanMessage[] — List of messages in the input or output. - `content` string — Text content of the message. - `id` string — Unique identifier of the message. - `role` string — Role of the message sender (e.g., user, assistant, system). - `tool_calls` LLMObsSpanToolCall[] — Tool calls made in this message. - `arguments` object — Arguments passed to the tool. - `name` string — Name of the tool called. - `tool_id` string — Identifier of the tool call. - `type` string — Type of the tool call. - `tool_results` LLMObsSpanToolResult[] — Tool results returned in this message. - `name` string — Name of the tool that produced this result. - `result` string — Result value returned by the tool. - `tool_id` string — Identifier of the corresponding tool call. - `type` string — Type of the tool result. - `value` string — Plain-text value of the input or output. - `parent_id` string — Identifier of the parent span, if any. - `span_id` string, required — Unique identifier of the span. - `span_kind` string, required — Kind of span (e.g., llm, agent, tool, task, workflow). - `start_ns` integer, required — Start time of the span in nanoseconds since Unix epoch. - `status` string, required — Status of the span (e.g., ok, error). - `tags` string[] — Tags associated with the span. - `tool_definitions` LLMObsSpanToolDefinition[] — Tool definitions available to the span. - `description` string — Description of what the tool does. - `name` string — Name of the tool. - `schema` object — JSON schema describing the tool's input parameters. - `version` string — Version of the tool definition. - `trace_id` string, required — Trace identifier this span belongs to. - `id` string, required — Unique identifier of the span. - `type` 'span', required — Resource type for an LLM Observability span. - `links` LLMObsSpansResponseLinks — Pagination links accompanying the spans response. - `next` string — URL to retrieve the next page of results. - `meta` LLMObsSpansResponseMeta, required — Metadata accompanying the spans response. - `elapsed` integer, required — Time elapsed for the query in milliseconds. - `page` LLMObsSpansResponsePage, required — Pagination cursor for the spans response. - `after` string — Cursor to retrieve the next page of results. Absent when there are no more results. - `request_id` string, required — Unique identifier for the request. - `status` string, required — Status of the query execution. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `429` — Too many requests --- [API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)