insights: align spans and traces query contract

specification/resources/insights/examples/curl/insights_post_spansSearch.yml

@@ -4,29 +4,28 @@ source: |-
     -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
-      "timeRange": {
+      "time_range": {
         "from": {"relative": "1h"},
         "to": {"relative": "now"}
       },
       "filter": {
-        "type": "and",
-        "expressions": [
-          {
-            "type": "condition",
-            "field": {"name": "service.name"},
-            "operator": "eq",
-            "value": {"type": "string", "value": "api-gateway"}
-          },
-          {
-            "type": "condition",
-            "field": {"name": "statusCode"},
-            "operator": "eq",
-            "value": {"type": "string", "value": "Error"}
-          }
-        ]
+        "and": {
+          "expressions": [
+            {"condition": {
+              "field": {"name": "service.name"},
+              "operator": "FILTER_OPERATOR_EQ",
+              "value": {"string_value": "api-gateway"}
+            }},
+            {"condition": {
+              "field": {"name": "status_code"},
+              "operator": "FILTER_OPERATOR_EQ",
+              "value": {"string_value": "Error"}
+            }}
+          ]
+        }
       },
-      "orderBy": [
-        {"field": {"name": "startTime"}, "direction": "desc"}
+      "order_by": [
+        {"field": {"name": "start_time"}, "direction": "desc"}
       ],
       "pagination": {"limit": 100}
     }' \

specification/resources/insights/examples/curl/insights_post_tracesSearch.yml

@@ -4,18 +4,19 @@ source: |-
     -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
-      "timeRange": {
+      "time_range": {
         "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"}
-        ]
+        "and": {
+          "expressions": [
+            {"condition": {"field": {"name": "service.name"}, "operator": "FILTER_OPERATOR_EQ", "value": {"string_value": "checkout-api"}}},
+            {"text_search": {"query": "timeout"}}
+          ]
+        }
       },
-      "orderBy": [{"field": {"name": "durationNs"}, "direction": "desc"}],
+      "order_by": [{"field": {"name": "duration_ns"}, "direction": "desc"}],
       "pagination": {"limit": 50}
     }' \
     "https://api.digitalocean.com/v2/insights/query/nyc3/traces/search"

specification/resources/insights/insights_get_trace.yml

@@ -29,8 +29,9 @@ description: >-
   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`).
+  JSON field names use snake_case (`trace_id`, `span_id`, `start_time`,
+  `end_time`, `duration_ns`, `service_name`, `status_code`,
+  `parent_span_id`).
 
 tags:
   - Insights

specification/resources/insights/insights_post_spansSearch.yml

@@ -8,8 +8,8 @@ description: >-
   time range, optional filter, ordering, and pagination.
 
   The time range must not exceed 7 days. `pagination.limit` defaults to 100 and
-  must be between 1 and 1000. Results are ordered by `startTime` descending by
-  default. Cursor-based pagination is not yet supported; `pagination.hasMore`
+  must be between 1 and 1000. Results are ordered by `start_time` descending by
+  default. Cursor-based pagination is not yet supported; `pagination.has_more`
   indicates whether additional spans matched beyond the returned page.
 
 tags:

specification/resources/insights/insights_post_tracesSearch.yml

@@ -12,10 +12,10 @@ description: >-
   `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.
+  `order_by` is set.
 
-  JSON field names are camelCase (`timeRange`, `orderBy`, `hasMore`,
-  `traceId`). Unknown request properties, invalid filters, and out-of-range
+  JSON field names use snake_case (`time_range`, `order_by`, `has_more`,
+  `trace_id`). 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.
@@ -48,7 +48,7 @@ requestBody:
         recent:
           summary: Most recent traces in the last 15 minutes
           value:
-            timeRange:
+            time_range:
               from:
                 relative: 15m
               to:
@@ -58,56 +58,62 @@ requestBody:
         filtered:
           summary: Traces from one service whose spans mention "timeout"
           value:
-            timeRange:
+            time_range:
               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
+              and:
+                expressions:
+                  - condition:
+                      field:
+                        name: service.name
+                      operator: FILTER_OPERATOR_EQ
+                      value:
+                        string_value: checkout-api
+                  - text_search:
+                      query: timeout
             pagination:
               limit: 100
         attributeIn:
           summary: Traces with error spans from either of two hosts
           value:
-            timeRange:
+            time_range:
               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
+              and:
+                expressions:
+                  - condition:
+                      field:
+                        name: status_code
+                      operator: FILTER_OPERATOR_EQ
+                      value:
+                        string_value: Error
+                  - condition:
+                      field:
+                        name: host.name
+                        scope: FIELD_SCOPE_RESOURCE
+                      operator: FILTER_OPERATOR_IN
+                      value:
+                        string_array_value:
+                          values:
+                            - web-01
+                            - web-02
         ordered:
           summary: Slowest traces first, ties broken by oldest start
           value:
-            timeRange:
+            time_range:
               from:
                 relative: 1h
               to:
                 relative: now
-            orderBy:
+            order_by:
               - field:
-                  name: durationNs
+                  name: duration_ns
                 direction: desc
               - field:
                   name: started

specification/resources/insights/models/span_record.yml

@@ -1,29 +1,29 @@
 type: object
 description: A single span returned by a spans search.
 properties:
-  traceId:
+  trace_id:
     type: string
     description: The trace identifier the span belongs to.
     example: "4bf92f3577b34da6a3ce929d0e0e4736"
-  spanId:
+  span_id:
     type: string
     description: The span identifier.
     example: "00f067aa0ba902b7"
-  parentSpanId:
+  parent_span_id:
     type: string
     description: The parent span identifier. Omitted for root spans.
     example: "00f067aa0ba902b6"
-  startTime:
+  start_time:
     type: string
     format: date-time
     description: The span start time.
     example: "2026-09-30T00:00:00Z"
-  endTime:
+  end_time:
     type: string
     format: date-time
     description: The span end time.
     example: "2026-09-30T00:00:01Z"
-  durationNs:
+  duration_ns:
     type: integer
     format: int64
     description: The span duration in nanoseconds.
@@ -36,15 +36,15 @@ properties:
     type: string
     description: The span kind.
     example: "Server"
-  statusCode:
+  status_code:
     type: string
     description: The span status code.
     example: "Ok"
-  statusMessage:
+  status_message:
     type: string
     description: The span status message. Omitted when empty.
     example: "connection reset by peer"
-  serviceName:
+  service_name:
     type: string
     description: The name of the service that emitted the span.
     example: "api-gateway"

specification/resources/insights/models/spans_filter_condition.yml

@@ -0,0 +1,40 @@
+type: object
+description: A single field comparison in a spans filter expression.
+required:
+  - field
+  - operator
+oneOf:
+  - properties:
+      operator:
+        type: string
+        enum:
+          - FILTER_OPERATOR_EXISTS
+        example: FILTER_OPERATOR_EXISTS
+  - required:
+      - value
+    properties:
+      operator:
+        type: string
+        enum:
+          - FILTER_OPERATOR_EQ
+          - FILTER_OPERATOR_NEQ
+          - FILTER_OPERATOR_IN
+          - FILTER_OPERATOR_GTE
+          - FILTER_OPERATOR_LTE
+        example: FILTER_OPERATOR_EQ
+properties:
+  field:
+    $ref: 'spans_filter_field.yml'
+  operator:
+    type: string
+    description: The comparison operator.
+    enum:
+      - FILTER_OPERATOR_EQ
+      - FILTER_OPERATOR_NEQ
+      - FILTER_OPERATOR_IN
+      - FILTER_OPERATOR_EXISTS
+      - FILTER_OPERATOR_GTE
+      - FILTER_OPERATOR_LTE
+    example: FILTER_OPERATOR_EQ
+  value:
+    $ref: 'spans_filter_value.yml'