diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml
index 6ac54ab7e..eba28b02b 100644
--- a/specification/DigitalOcean-public.v2.yaml
+++ b/specification/DigitalOcean-public.v2.yaml
@@ -1840,6 +1840,14 @@ paths:
     post:
       $ref: "resources/insights/insights_post_logsSearch.yml"
 
+  /v2/insights/query/{region}/traces/search:
+    post:
+      $ref: "resources/insights/insights_post_tracesSearch.yml"
+
+  /v2/insights/query/{region}/traces/{trace_id}:
+    get:
+      $ref: "resources/insights/insights_get_trace.yml"
+
   /v2/insights/query/{region}/spans/search:
     post:
       $ref: "resources/insights/insights_post_spansSearch.yml"
diff --git a/specification/resources/insights/examples/curl/insights_get_trace.yml b/specification/resources/insights/examples/curl/insights_get_trace.yml
new file mode 100644
index 000000000..e7a4f2e55
--- /dev/null
+++ b/specification/resources/insights/examples/curl/insights_get_trace.yml
@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/insights/query/nyc3/traces/7b0b4e56abab38362b24e5498eb9ec64?from=24h&to=now"
diff --git a/specification/resources/insights/examples/curl/insights_post_tracesSearch.yml b/specification/resources/insights/examples/curl/insights_post_tracesSearch.yml
new file mode 100644
index 000000000..54d80abb3
--- /dev/null
+++ b/specification/resources/insights/examples/curl/insights_post_tracesSearch.yml
@@ -0,0 +1,21 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "timeRange": {
+        "from": {"relative": "24h"},
+        "to": {"relative": "now"}
+      },
+      "filter": {
+        "type": "and",
+        "expressions": [
+          {"type": "condition", "field": {"name": "service.name"}, "operator": "eq", "value": "checkout-api"},
+          {"type": "text_search", "query": "timeout"}
+        ]
+      },
+      "orderBy": [{"field": {"name": "durationNs"}, "direction": "desc"}],
+      "pagination": {"limit": 50}
+    }' \
+    "https://api.digitalocean.com/v2/insights/query/nyc3/traces/search"
diff --git a/specification/resources/insights/insights_get_trace.yml b/specification/resources/insights/insights_get_trace.yml
new file mode 100644
index 000000000..106adfa28
--- /dev/null
+++ b/specification/resources/insights/insights_get_trace.yml
@@ -0,0 +1,77 @@
+operationId: insights_get_trace
+
+summary: Retrieve an existing trace
+
+description: >-
+  To retrieve a single trace and all of its spans, send a GET request to
+  `/v2/insights/query/{region}/traces/{trace_id}`.
+
+  Only spans that started within the lookup window are returned. The window
+  defaults to the last 7 days and can be narrowed with the `from` and `to`
+  query parameters; it must not exceed 7 days, and `from` must not be after
+  `to`. Spans are returned ordered by start time. At most 10,000 spans are
+  returned; `truncated` is `true` when the trace has more.
+
+  A trace ID with no spans in the window returns `404`, as do malformed or
+  uppercase trace IDs. A trace is only resolvable in the region that ingested
+  it; querying another region also returns `404`.
+
+  Supported regions are `ams2`, `ams3`, `atl1`, `blr1`, `fra1`, `lon1`,
+  `mem1`, `nyc1`, `nyc2`, `nyc3`, `ric1`, `sfo1`, `sfo2`, `sfo3`, `sgp1`,
+  `syd1`, and `tor1`. Requests time out after 60 seconds.
+
+  Errors produced by the traces service (`400`, and `404` when no trace is
+  found) have a `text/plain` body containing a short message. Authentication
+  and authorization errors (`401`, `403`), rate limiting (`429`), and routing
+  errors (for example, `404` for an unknown region) come from the API gateway
+  and use the standard JSON error object with `id` and `message`. `403` is
+  also returned for accounts that are in a trial or not in good standing. If
+  the regional traces backend cannot be reached, the response is `502` with a
+  `text/plain` body.
+
+  JSON field names are camelCase (`traceId`, `spanId`, `startTime`, `endTime`,
+  `durationNs`, `serviceName`, `statusCode`, `parentSpanId`).
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: 'parameters.yml#/region'
+  - $ref: 'parameters.yml#/trace_id'
+  - $ref: 'parameters.yml#/trace_from'
+  - $ref: 'parameters.yml#/trace_to'
+
+responses:
+  '200':
+    $ref: 'responses/trace.yml'
+
+  '400':
+    $ref: 'responses/traces_bad_request.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '403':
+    $ref: '../../shared/responses/forbidden.yml'
+
+  '404':
+    $ref: 'responses/traces_not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  '502':
+    $ref: 'responses/traces_bad_gateway.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/insights_get_trace.yml'
+
+security:
+  - bearer_auth:
+    - 'insights:read'
diff --git a/specification/resources/insights/insights_post_tracesSearch.yml b/specification/resources/insights/insights_post_tracesSearch.yml
new file mode 100644
index 000000000..a1f8b753a
--- /dev/null
+++ b/specification/resources/insights/insights_post_tracesSearch.yml
@@ -0,0 +1,151 @@
+operationId: insights_post_tracesSearch
+
+summary: Search traces
+
+description: >-
+  To search traces in a region, send a POST request to
+  `/v2/insights/query/{region}/traces/search` with a JSON body describing the
+  time range, optional filter, ordering, and pagination.
+
+  Each result is one trace, aggregated from all of its spans in the time
+  range. A trace is included when at least one of its spans matches
+  `filter`. The time range must not exceed 7 days (`168h`).
+  `pagination.limit` defaults to 100 (also used when `limit` is `0`) and must
+  be between 0 and 1000. Results are ordered by `started` descending unless
+  `orderBy` is set.
+
+  JSON field names are camelCase (`timeRange`, `orderBy`, `hasMore`,
+  `traceId`). Unknown request properties, invalid filters, and out-of-range
+  values are rejected with `400`.
+
+  Each request searches a single region; there is no multi-region search.
+  Supported regions are `ams2`, `ams3`, `atl1`, `blr1`, `fra1`, `lon1`,
+  `mem1`, `nyc1`, `nyc2`, `nyc3`, `ric1`, `sfo1`, `sfo2`, `sfo3`, `sgp1`,
+  `syd1`, and `tor1`. Requests time out after 60 seconds.
+
+  Errors produced by the traces service (`400`) have a `text/plain` body
+  containing a short message. Authentication and authorization errors
+  (`401`, `403`), rate limiting (`429`), and routing errors (for example,
+  `404` for an unknown region) come from the API gateway and use the standard
+  JSON error object with `id` and `message`. `403` is also returned for
+  accounts that are in a trial or not in good standing. If the regional
+  traces backend cannot be reached, the response is `502` with a
+  `text/plain` body.
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: 'parameters.yml#/region'
+
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        $ref: 'models/traces_search_request.yml'
+      examples:
+        recent:
+          summary: Most recent traces in the last 15 minutes
+          value:
+            timeRange:
+              from:
+                relative: 15m
+              to:
+                relative: now
+            pagination:
+              limit: 50
+        filtered:
+          summary: Traces from one service whose spans mention "timeout"
+          value:
+            timeRange:
+              from:
+                relative: 24h
+              to:
+                relative: now
+            filter:
+              type: and
+              expressions:
+                - type: condition
+                  field:
+                    name: service.name
+                  operator: eq
+                  value: checkout-api
+                - type: text_search
+                  query: timeout
+            pagination:
+              limit: 100
+        attributeIn:
+          summary: Traces with error spans from either of two hosts
+          value:
+            timeRange:
+              from:
+                absolute: "2026-10-09T00:00:00Z"
+              to:
+                absolute: "2026-10-09T06:00:00Z"
+            filter:
+              type: and
+              expressions:
+                - field:
+                    name: statusCode
+                  operator: eq
+                  value: Error
+                - field:
+                    name: host.name
+                    scope: resource
+                  operator: in
+                  value:
+                    - web-01
+                    - web-02
+        ordered:
+          summary: Slowest traces first, ties broken by oldest start
+          value:
+            timeRange:
+              from:
+                relative: 1h
+              to:
+                relative: now
+            orderBy:
+              - field:
+                  name: durationNs
+                direction: desc
+              - field:
+                  name: started
+                direction: asc
+            pagination:
+              limit: 20
+
+responses:
+  '200':
+    $ref: 'responses/traces_search.yml'
+
+  '400':
+    $ref: 'responses/traces_bad_request.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '403':
+    $ref: '../../shared/responses/forbidden.yml'
+
+  '404':
+    $ref: 'responses/traces_not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  '502':
+    $ref: 'responses/traces_bad_gateway.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/insights_post_tracesSearch.yml'
+
+security:
+  - bearer_auth:
+    - 'insights:read'
diff --git a/specification/resources/insights/models/traces_field_ref.yml b/specification/resources/insights/models/traces_field_ref.yml
new file mode 100644
index 000000000..6064c4d10
--- /dev/null
+++ b/specification/resources/insights/models/traces_field_ref.yml
@@ -0,0 +1,41 @@
+type: object
+description: A reference to a span field, used in filters and `orderBy`.
+additionalProperties: false
+required:
+  - name
+properties:
+  name:
+    type: string
+    description: >-
+      The field name. Without `scope`, these names (case-insensitive) resolve
+      to built-in span columns: `traceId` (`trace.id`, `trace_id`), `spanId`
+      (`span.id`, `span_id`), `parentSpanId` (`parent.span.id`,
+      `parent_span_id`), `startTime` (`start_time`, `timestamp`), `endTime`
+      (`end_time`), `durationNs` (`duration`, in nanoseconds), `name`
+      (`span.name`), `kind` (`span.kind`), `statusCode` (`status.code`,
+      `status_code`), `statusMessage` (`status.message`, `status_message`),
+      and `serviceName` (`service.name`, `service_name`). Any other name is
+      looked up as a span attribute, falling back to a resource attribute.
+      With `scope` set, `name` is always treated as an attribute key.
+      Attribute keys may contain only letters, digits, and `.`, `_`, `-`,
+      `/`, `:`, `@`.
+
+
+      In traces `orderBy`, `name` must be a trace-level sort field instead;
+      see the `orderBy` field description.
+    example: service.name
+  scope:
+    type: string
+    description: >-
+      Restricts the lookup to one attribute map (case-insensitive).
+      `resource` (or `resource.attributes`) reads resource attributes;
+      `attribute` (or `attributes`, `span.attributes`) reads span attributes.
+      Omit to use the built-in column mapping described for `name`. Ignored
+      in traces `orderBy`.
+    enum:
+      - resource
+      - resource.attributes
+      - attribute
+      - attributes
+      - span.attributes
+    example: resource
diff --git a/specification/resources/insights/models/traces_filter_expression.yml b/specification/resources/insights/models/traces_filter_expression.yml
new file mode 100644
index 000000000..7bee5ec8a
--- /dev/null
+++ b/specification/resources/insights/models/traces_filter_expression.yml
@@ -0,0 +1,82 @@
+type: object
+description: >-
+  A node in a traces filter tree. Every node is the same flat object; `type`
+  selects which other properties apply:
+
+  - `condition` (default when `type` is omitted): compares `field` to `value`
+  using `operator`.
+
+  - `and` / `or`: combines the nodes in `expressions` (1 to 32 children).
+
+  - `not`: negates the single node in `expressions` (exactly one child).
+
+  - `text_search`: case-insensitive substring match of `query` against the
+  span name, service name, and span status message.
+
+
+  A trace matches when at least one of its spans in the time range matches
+  the filter. Trees may be nested at most 16 levels deep and contain at most
+  256 nodes in total. Unknown properties are rejected.
+additionalProperties: false
+properties:
+  type:
+    type: string
+    description: The node type. Matching is case-insensitive.
+    enum:
+      - condition
+      - and
+      - or
+      - not
+      - text_search
+    default: condition
+    example: condition
+  expressions:
+    type: array
+    description: >-
+      Child nodes for `and`, `or`, and `not`. `and` and `or` accept 1 to 32
+      children; `not` requires exactly one.
+    minItems: 1
+    maxItems: 32
+    items:
+      $ref: 'traces_filter_expression.yml'
+  field:
+    $ref: 'traces_field_ref.yml'
+  operator:
+    type: string
+    description: >-
+      The comparison operator for a `condition` node. Matching is
+      case-insensitive, and the symbol forms `=`, `!=`, `>`, `>=`, `<`, and
+      `<=` are accepted as aliases for `eq`, `neq`, `gt`, `gte`, `lt`, and
+      `lte`. `exists` matches spans where the field is present and non-empty
+      and ignores `value`. `in` requires an array `value` with 1 to 100
+      entries. `neq` on string fields also matches spans where the field is
+      absent.
+    enum:
+      - eq
+      - neq
+      - in
+      - exists
+      - gt
+      - gte
+      - lt
+      - lte
+    example: eq
+  value:
+    $ref: 'traces_filter_value.yml'
+  query:
+    type: string
+    description: >-
+      The search string for a `text_search` node. Leading and trailing
+      whitespace is trimmed; the trimmed string must be non-empty.
+    maxLength: 256
+    example: checkout
+example:
+  type: and
+  expressions:
+    - type: condition
+      field:
+        name: service.name
+      operator: eq
+      value: checkout-api
+    - type: text_search
+      query: timeout
diff --git a/specification/resources/insights/models/traces_filter_value.yml b/specification/resources/insights/models/traces_filter_value.yml
new file mode 100644
index 000000000..d03942efd
--- /dev/null
+++ b/specification/resources/insights/models/traces_filter_value.yml
@@ -0,0 +1,73 @@
+description: >-
+  The comparison value for a filter `condition`. Pass either a bare JSON
+  literal (string, number, boolean, or array for `in`) or a typed object
+  `{"type": "...", "value": ...}`. String values are coerced to the field's
+  type: numeric fields such as `durationNs` parse the string as a number, and
+  time fields such as `startTime` accept the same absolute formats as
+  `timeRange` (RFC3339 or Unix seconds/milliseconds/microseconds/nanoseconds).
+example: checkout-api
+oneOf:
+  - type: string
+    description: A bare string literal.
+    example: checkout-api
+  - type: number
+    description: A bare number literal.
+    example: 500000000
+  - type: boolean
+    description: A bare boolean literal.
+    example: true
+  - type: array
+    description: A bare array of values, used with the `in` operator.
+    minItems: 1
+    maxItems: 100
+    items:
+      oneOf:
+        - type: string
+        - type: number
+        - type: boolean
+    example:
+      - checkout-api
+      - payments-api
+  - type: object
+    description: >-
+      A typed scalar value. `type` is case-insensitive; `int`, `integer`, and
+      `float` are accepted as aliases for `number`, and `boolean` for `bool`.
+    additionalProperties: false
+    required:
+      - type
+      - value
+    properties:
+      type:
+        type: string
+        enum:
+          - string
+          - number
+          - bool
+        example: number
+      value:
+        oneOf:
+          - type: string
+          - type: number
+          - type: boolean
+        example: 500000000
+  - type: object
+    description: A typed string list, used with the `in` operator.
+    additionalProperties: false
+    required:
+      - type
+      - value
+    properties:
+      type:
+        type: string
+        enum:
+          - string_array
+        example: string_array
+      value:
+        type: array
+        minItems: 1
+        maxItems: 100
+        items:
+          type: string
+        example:
+          - checkout-api
+          - payments-api
diff --git a/specification/resources/insights/models/traces_order_by.yml b/specification/resources/insights/models/traces_order_by.yml
new file mode 100644
index 000000000..f6cce3541
--- /dev/null
+++ b/specification/resources/insights/models/traces_order_by.yml
@@ -0,0 +1,28 @@
+type: object
+description: >-
+  A sort clause for traces search results. Supported `field.name` values
+  (case-insensitive) are `started` (aliases `startTime`, `start_time`,
+  `timestamp`), `durationNs` (`duration`), `serviceName` (`service.name`,
+  `service_name`), `traceId` (`trace.id`, `trace_id`), `errorCount`
+  (`error_count`), `spanCount` (`span_count`), and `status`. Any other name
+  returns `400`.
+
+
+  Sorting by `started` is exact. For every other field, the server first
+  selects the most recent matching traces by start time (up to the requested
+  limit) and then sorts only those traces, so results are not a global top-N
+  across the whole time range.
+additionalProperties: false
+required:
+  - field
+properties:
+  field:
+    $ref: 'traces_field_ref.yml'
+  direction:
+    type: string
+    description: The sort direction (case-insensitive). Defaults to `desc`.
+    enum:
+      - asc
+      - desc
+    default: desc
+    example: desc
diff --git a/specification/resources/insights/models/traces_pagination_request.yml b/specification/resources/insights/models/traces_pagination_request.yml
new file mode 100644
index 000000000..f668b142d
--- /dev/null
+++ b/specification/resources/insights/models/traces_pagination_request.yml
@@ -0,0 +1,18 @@
+type: object
+description: >-
+  Limits the size of a traces search result set. There is no cursor; use
+  `pagination.hasMore` in the response to tell whether more traces matched,
+  and narrow the time range or filter to see them.
+additionalProperties: false
+properties:
+  limit:
+    type: integer
+    format: int32
+    description: >-
+      Maximum number of traces to return. Omitted or `0` uses the default of
+      100. Negative values or values above 1000 return `400`; they are not
+      clamped.
+    default: 100
+    minimum: 0
+    maximum: 1000
+    example: 50
diff --git a/specification/resources/insights/models/traces_pagination_response.yml b/specification/resources/insights/models/traces_pagination_response.yml
new file mode 100644
index 000000000..a41c12440
--- /dev/null
+++ b/specification/resources/insights/models/traces_pagination_response.yml
@@ -0,0 +1,9 @@
+type: object
+description: Pagination response.
+required:
+  - hasMore
+properties:
+  hasMore:
+    type: boolean
+    description: Whether more results matched the query than were returned.
+    example: false
diff --git a/specification/resources/insights/models/traces_search_request.yml b/specification/resources/insights/models/traces_search_request.yml
new file mode 100644
index 000000000..dcd38069b
--- /dev/null
+++ b/specification/resources/insights/models/traces_search_request.yml
@@ -0,0 +1,17 @@
+type: object
+description: Request body for searching traces. Unknown properties are rejected.
+additionalProperties: false
+required:
+  - timeRange
+properties:
+  timeRange:
+    $ref: 'traces_time_range.yml'
+  filter:
+    $ref: 'traces_filter_expression.yml'
+  orderBy:
+    type: array
+    description: Sort clauses applied in order. Defaults to `started` descending.
+    items:
+      $ref: 'traces_order_by.yml'
+  pagination:
+    $ref: 'traces_pagination_request.yml'
diff --git a/specification/resources/insights/models/traces_search_response.yml b/specification/resources/insights/models/traces_search_response.yml
new file mode 100644
index 000000000..2fc6b4a40
--- /dev/null
+++ b/specification/resources/insights/models/traces_search_response.yml
@@ -0,0 +1,13 @@
+type: object
+description: Response body for a traces search.
+required:
+  - data
+  - pagination
+properties:
+  data:
+    type: array
+    description: Matching traces. Empty when no traces match.
+    items:
+      $ref: 'traces_trace_summary.yml'
+  pagination:
+    $ref: 'traces_pagination_response.yml'
diff --git a/specification/resources/insights/models/traces_span_record.yml b/specification/resources/insights/models/traces_span_record.yml
new file mode 100644
index 000000000..523061224
--- /dev/null
+++ b/specification/resources/insights/models/traces_span_record.yml
@@ -0,0 +1,73 @@
+type: object
+description: A single span belonging to a trace.
+required:
+  - traceId
+  - spanId
+properties:
+  traceId:
+    type: string
+    description: The trace this span belongs to.
+    example: "7b0b4e56abab38362b24e5498eb9ec64"
+  spanId:
+    type: string
+    description: The span identifier.
+    example: "e7867486e45cda47"
+  parentSpanId:
+    type: string
+    description: The parent span identifier. Omitted for the root span.
+    example: "a2fb4a1d1a96d312"
+  startTime:
+    type: string
+    format: date-time
+    description: The span start time.
+    example: "2026-10-09T06:44:37Z"
+  endTime:
+    type: string
+    format: date-time
+    description: The span end time.
+    example: "2026-10-09T06:44:39Z"
+  durationNs:
+    type: integer
+    format: int64
+    description: Span duration in nanoseconds.
+    example: 200000000
+  name:
+    type: string
+    description: The span name, typically the operation being performed.
+    example: "GET /checkout"
+  kind:
+    type: string
+    description: >-
+      The OpenTelemetry span kind as a string, for example `Server`,
+      `Client`, or `Internal`.
+    example: "Server"
+  statusCode:
+    type: string
+    description: >-
+      The OpenTelemetry span status code as a string: `Unset`, `Ok`, or
+      `Error`.
+    example: "Error"
+  statusMessage:
+    type: string
+    description: The status description. Omitted when empty.
+    example: "upstream timeout"
+  serviceName:
+    type: string
+    description: >-
+      The service that emitted the span. Omitted when the span has no
+      service.name resource attribute.
+    example: "checkout-api"
+  resource:
+    type: object
+    description: Resource attributes associated with the span.
+    additionalProperties:
+      type: string
+    example:
+      service.name: "checkout-api"
+  attributes:
+    type: object
+    description: Span attributes. Omitted when empty.
+    additionalProperties:
+      type: string
+    example:
+      http.method: "GET"
diff --git a/specification/resources/insights/models/traces_time_instant.yml b/specification/resources/insights/models/traces_time_instant.yml
new file mode 100644
index 000000000..f35931dda
--- /dev/null
+++ b/specification/resources/insights/models/traces_time_instant.yml
@@ -0,0 +1,23 @@
+type: object
+description: >-
+  A single point in time. Set `absolute` or `relative`; if both are set,
+  `absolute` is used.
+additionalProperties: false
+minProperties: 1
+properties:
+  absolute:
+    type: string
+    description: >-
+      An absolute timestamp, either RFC3339 (with optional fractional
+      seconds) or a Unix epoch integer as a decimal string. Epoch precision
+      is inferred from magnitude: seconds, milliseconds, microseconds, or
+      nanoseconds.
+    example: "2026-10-09T00:00:00Z"
+  relative:
+    type: string
+    description: >-
+      A time relative to now. Use `now` for the current time, a bare duration
+      such as `15m` or `24h` to look back from now, or an offset such as
+      `now-2h` or `now+30m`. Supported units are `s`, `m`, `h`, `d`, and `w`;
+      decimal amounts such as `1.5h` are allowed.
+    example: "15m"
diff --git a/specification/resources/insights/models/traces_time_range.yml b/specification/resources/insights/models/traces_time_range.yml
new file mode 100644
index 000000000..b3e70de35
--- /dev/null
+++ b/specification/resources/insights/models/traces_time_range.yml
@@ -0,0 +1,13 @@
+type: object
+description: >-
+  An inclusive query time window. Both bounds are required, `from` must not
+  be after `to`, and the window must not exceed 7 days (`168h`).
+additionalProperties: false
+required:
+  - from
+  - to
+properties:
+  from:
+    $ref: 'traces_time_instant.yml'
+  to:
+    $ref: 'traces_time_instant.yml'
diff --git a/specification/resources/insights/models/traces_trace_response.yml b/specification/resources/insights/models/traces_trace_response.yml
new file mode 100644
index 000000000..3f8744e78
--- /dev/null
+++ b/specification/resources/insights/models/traces_trace_response.yml
@@ -0,0 +1,18 @@
+type: object
+description: A single trace and all of its spans.
+properties:
+  traceId:
+    type: string
+    description: The trace identifier.
+    example: "7b0b4e56abab38362b24e5498eb9ec64"
+  spans:
+    type: array
+    description: Every span in the trace, ordered by start time.
+    items:
+      $ref: 'traces_span_record.yml'
+  truncated:
+    type: boolean
+    description: >-
+      True when the trace has more spans than were returned in this response.
+      Omitted when false.
+    example: false
diff --git a/specification/resources/insights/models/traces_trace_summary.yml b/specification/resources/insights/models/traces_trace_summary.yml
new file mode 100644
index 000000000..5d7ffbe82
--- /dev/null
+++ b/specification/resources/insights/models/traces_trace_summary.yml
@@ -0,0 +1,56 @@
+type: object
+description: >-
+  A single trace returned by a traces search. One row per trace, aggregated
+  from its spans. Every field except `traceId` is omitted when it holds its
+  zero value (for example, `errorCount` is absent when no spans errored).
+required:
+  - traceId
+properties:
+  traceId:
+    type: string
+    description: The trace identifier.
+    example: "bef35030c4024f42fb88041fea062e97"
+  started:
+    type: string
+    format: date-time
+    description: The start time of the earliest span in the trace, in RFC 3339 format.
+    example: "2026-10-09T09:21:39.99Z"
+  serviceName:
+    type: string
+    description: >-
+      The service that emitted the root span. Omitted when the root span has
+      no service.name resource attribute.
+    example: "checkout-api"
+  durationNs:
+    type: integer
+    format: int64
+    description: Wall-clock duration of the trace in nanoseconds.
+    example: 10000000
+  spanCount:
+    type: integer
+    format: int32
+    description: The number of spans in the trace.
+    example: 1
+  errorCount:
+    type: integer
+    format: int32
+    description: >-
+      The number of spans in the trace with an `Error` status code. Omitted
+      when zero.
+    example: 1
+  status:
+    type: string
+    description: >-
+      The rolled-up status of the trace. `Error` if any span has an `Error`
+      status code, otherwise `Ok`.
+    enum:
+      - Ok
+      - Error
+    example: "Ok"
+  spanNames:
+    type: array
+    description: The distinct span names present in the trace.
+    items:
+      type: string
+    example:
+      - "checkout-api-root"
diff --git a/specification/resources/insights/parameters.yml b/specification/resources/insights/parameters.yml
index a8238d184..fb98ecc42 100644
--- a/specification/resources/insights/parameters.yml
+++ b/specification/resources/insights/parameters.yml
@@ -74,6 +74,43 @@ region:
     type: string
   example: nyc3
 
+trace_id:
+  in: path
+  name: trace_id
+  description: >-
+    The OpenTelemetry trace ID to retrieve, as 32 lowercase hexadecimal
+    characters. IDs are matched exactly; an ID with no spans in the lookup
+    window returns `404`. Malformed or uppercase IDs are not rejected with
+    `400`; they also return `404`.
+  required: true
+  schema:
+    type: string
+  example: 7b0b4e56abab38362b24e5498eb9ec64
+
+trace_from:
+  in: query
+  name: from
+  required: false
+  description: >-
+    Start of the trace lookup window. Accepts a relative time (`now`, a bare
+    duration such as `24h` to look back from now, or `now-2h`) or an absolute
+    time (RFC3339, or a Unix epoch integer in seconds, milliseconds,
+    microseconds, or nanoseconds). Defaults to 7 days before now.
+  schema:
+    type: string
+  example: 24h
+
+trace_to:
+  in: query
+  name: to
+  required: false
+  description: >-
+    End of the trace lookup window, in the same formats as `from`. Defaults to
+    now.
+  schema:
+    type: string
+  example: now
+
 label_name:
   in: path
   name: name
diff --git a/specification/resources/insights/responses/trace.yml b/specification/resources/insights/responses/trace.yml
new file mode 100644
index 000000000..fbef6847c
--- /dev/null
+++ b/specification/resources/insights/responses/trace.yml
@@ -0,0 +1,14 @@
+description: The trace and its spans.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      $ref: '../models/traces_trace_response.yml'
diff --git a/specification/resources/insights/responses/traces_bad_gateway.yml b/specification/resources/insights/responses/traces_bad_gateway.yml
new file mode 100644
index 000000000..9370642de
--- /dev/null
+++ b/specification/resources/insights/responses/traces_bad_gateway.yml
@@ -0,0 +1,17 @@
+description: >-
+  The regional traces backend could not be reached. The body is a short
+  plain-text message.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  text/plain:
+    schema:
+      type: string
+    example: Bad Gateway
diff --git a/specification/resources/insights/responses/traces_bad_request.yml b/specification/resources/insights/responses/traces_bad_request.yml
new file mode 100644
index 000000000..e3f7d1f55
--- /dev/null
+++ b/specification/resources/insights/responses/traces_bad_request.yml
@@ -0,0 +1,36 @@
+description: >-
+  The request was rejected by the traces service, for example because the
+  body is malformed, a field is out of range, or the time range is invalid.
+  The body is a short plain-text message.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  text/plain:
+    schema:
+      type: string
+    examples:
+      limit_above_maximum:
+        summary: Pagination limit above maximum
+        value: pagination.limit exceeds maximum of 1000
+      search_time_range_too_long:
+        summary: Search time range longer than 7 days
+        value: timeRange exceeds maximum of 168h0m0s
+      trace_window_too_long:
+        summary: Trace lookup window longer than 7 days
+        value: time range exceeds maximum of 168h0m0s
+      invalid_order_direction:
+        summary: Unsupported orderBy direction
+        value: invalid orderBy direction "SORT_DIRECTION_ASC"
+      from_after_to:
+        summary: Time range start after end
+        value: timeRange.from must be before or equal to timeRange.to
+      unknown_property:
+        summary: Unknown or malformed request body property
+        value: invalid request body
diff --git a/specification/resources/insights/responses/traces_not_found.yml b/specification/resources/insights/responses/traces_not_found.yml
new file mode 100644
index 000000000..fdaefe0ad
--- /dev/null
+++ b/specification/resources/insights/responses/traces_not_found.yml
@@ -0,0 +1,25 @@
+description: >-
+  The trace or region was not found. When the traces service finds no
+  matching trace, the body is the plain-text message `trace not found`. When
+  the region is unknown or does not serve traces, the API gateway returns a
+  JSON error object.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  text/plain:
+    schema:
+      type: string
+    example: trace not found
+  application/json:
+    schema:
+      $ref: '../../../shared/models/error.yml'
+    example:
+      id: not_found
+      message: Your request could not be routed.
diff --git a/specification/resources/insights/responses/traces_search.yml b/specification/resources/insights/responses/traces_search.yml
new file mode 100644
index 000000000..6991e7d4d
--- /dev/null
+++ b/specification/resources/insights/responses/traces_search.yml
@@ -0,0 +1,26 @@
+description: Traces search result.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      $ref: '../models/traces_search_response.yml'
+    example:
+      data:
+        - traceId: "bef35030c4024f42fb88041fea062e97"
+          started: "2026-10-09T09:21:39.99Z"
+          serviceName: "checkout-api"
+          durationNs: 10000000
+          status: "Ok"
+          spanCount: 1
+          spanNames:
+            - "checkout-api-root"
+      pagination:
+        hasMore: false