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

## Request

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

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