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

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/llm-obs/v1/spans/events/search`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

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.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)