---
title: "List LLM Observability spans"
method: GET
path: "/api/v2/llm-obs/v1/spans/events"
tags: ["LLM Observability"]
---

# List LLM Observability spans

`GET /api/v2/llm-obs/v1/spans/events`

List LLM Observability spans matching the specified filters.

## Query parameters

- `filter[from]` string
- `filter[to]` string
- `filter[query]` string
- `filter[span_id]` string
- `filter[trace_id]` string
- `filter[span_kind]` string
- `filter[span_name]` string
- `filter[ml_app]` string
- `page[limit]` integer
- `page[cursor]` string
- `sort` string
- `include_attachments` boolean

## 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)