[adityasingh-beep]

What

Documents the public Insights spans search endpoint:

POST /v2/insights/query/{region}/spans/search

It mirrors the existing /v2/insights/query/{region}/logs/search operation. Added:

• Operation (insights_post_spansSearch.yml) — insights:read scope, region path parameter, standard shared error responses.
• Request model (spans_search_request) — timeRange (required), filter, orderBy, pagination.
• Filter grammar (spans_filter_expression) — condition / and / or / not / text_search nodes; operators eq, neq, gt, gte, lt, lte, in, exists; field scoping (resource / attributes); and a spans_filter_value that accepts a bare scalar/array or a typed {type,value} wrapper.
• Time range (spans_time_range / spans_time_bound) — relative or absolute bounds, 7-day max window.
• Response model (spans_search_response + span_record) — the full span record and pagination.hasMore.
• A cURL example under examples/curl/.

Contract

Field names and the filter grammar match the querysvc/tracesapi backend (camelCase JSON, DisallowUnknownFields). The request path, method, and insights:read auth match the merged Edge/queryrouter routing.

Validation

• make bundle + make lint pass (0 errors).
• Validated end-to-end against the live stage2 s2r1 cell: routing, PAT auth, request acceptance, the full populated span_record, the complete filter grammar (condition/and/or/not/text_search, all operators, attribute scope, both value shapes), ordering, pagination (hasMore), and negative cases (400 for missing/invalid/unknown-field/unsupported-operator).

Notes

• Error responses are documented with the standard DO JSON envelope. The backend currently returns plain-text error bodies for this endpoint; that is tracked separately as a backend fix and does not affect this contract.

[adityasingh-beep]

Additional validation — live populated data

Beyond make bundle + make lint (0 errors), the endpoint was exercised end-to-end against the live deployed service with real populated spans (region nyc2):

• Response envelope matches spans_search_response (data[] + pagination.hasMore), e.g. count: 50, hasMore: true.
• Every span_record field validated against live values: traceId, spanId, parentSpanId, startTime/endTime (RFC3339Nano), durationNs (int64), name, kind, statusCode, resource, attributes.
• statusCode observed as Unset in addition to Ok/Error — covered since it's documented as a free-form string.
• Optional fields (serviceName, statusMessage, region) are correctly omitted when empty; no undocumented fields appeared.
• Full filter grammar (condition/and/or/not/text_search; eq/neq/gt/gte/lt/lte/in/exists), scope: attributes, both spans_filter_value shapes, ordering, pagination (hasMore), and negative cases (400) were validated in a lower environment.