Get Traces

Get traces within a time range.

Requires a valid JWT token with the read:traces permission.

Retrieves a paginated list of aggregated information for traces by selecting root spans (parent_span_id is null or span_kind = SPAN_KIND_SERVER) within the specified time range, aggregating trace duration, span count, and total cost.

By default, filters apply only to root spans. Set search_child_spans=true to apply filters across all spans, returning traces where at least one span meets the conditions.

Traces can be filtered with an expression that supports nested AND/OR conditions on the following fields:

Identifiers

Field	Description
trace_id	Trace identifier
span_id	Span identifier

Span fields

Field	Description
span_attributes.*	Any span attribute (e.g., span_attributes.http.method)
resource_attributes.*	Any resource attribute
span_kind	Span kind
span_name	Span name
service_name	Service name (equivalent to resource_attributes.service.name)
unit	Unit (equivalent to resource_attributes.unomiq_unit)
duration_ms	Span duration in milliseconds

Billing & Usage

Field	Description
billing.resource_type	Resource type (e.g., db_job, api_request, llm_generate_content)
billing.resource_name	Billing resource name
billing.service_id	Billing service ID
billing.service_name	Billing service name
billing.sku_id	Billing SKU ID
billing.sku_name	Billing SKU name
billing.region	Billing region
cost	Cost
usage.amount	Usage amount
usage.unit	Usage unit

POST /traces

Get Traces

cURL

curl --request POST \
  --url https://engine-api.unomiq.com/traces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Unomiq-App-Id: <x-unomiq-app-id>' \
  --data '
{
  "filter": {
    "and": [
      {
        "field": "span_attributes.http.status_code",
        "op": "gte",
        "value": "200"
      },
      {
        "field": "span_attributes.http.status_code",
        "op": "lte",
        "value": "299"
      },
      {
        "or": [
          {
            "field": "span_kind",
            "op": "eq",
            "value": "SERVER"
          },
          {
            "field": "span_kind",
            "op": "eq",
            "value": "CLIENT"
          }
        ]
      }
    ]
  }
}
'

200

{
  "data": [
    {
      "trace_id": "<string>",
      "span_name": "<string>",
      "duration_ms": 123,
      "spans_count": 123,
      "total_cost": 123,
      "min_start_time_unix_nano": 123,
      "service_name": "<string>",
      "unit": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Unomiq-App-Id · string · required

Query Parameters

start_time · string<date-time> · required

Start datetime (inclusive)

Example:

"2025-01-15T00:00:00Z"

end_time · string<date-time> · required

End datetime (exclusive)

Example:

"2025-01-16T00:00:00Z"

page · integer · default: 1

Page number for pagination (1-indexed)

Required range: x >= 1

limit · integer · default: 20

Number of items per page

Required range: 1 <= x <= 100

search_child_spans · boolean · default: false

When true, apply filters to all spans including child spans. When false, apply filters only to root spans.

Body

application/json

Request model for query filter.

filter · Condition · object

A single filter condition.

Condition

AndGroup

OrGroup

Show child attributes

Example:

{
  "and": [
    {
      "field": "span_attributes.http.status_code",
      "op": "gte",
      "value": "200"
    },
    {
      "field": "span_attributes.http.status_code",
      "op": "lte",
      "value": "299"
    },
    {
      "or": [
        {
          "field": "span_kind",
          "op": "eq",
          "value": "SERVER"
        },
        {
          "field": "span_kind",
          "op": "eq",
          "value": "CLIENT"
        }
      ]
    }
  ]
}

Response

200

application/json

Successful Response

Paginated response for root traces.

data · RootTrace · object[] · required

Show child attributes

pagination · PaginationInfo · object · required

Pagination metadata.

Show child attributes