Diagnose services

Root-cause an incident for one or more services over a time window. Returns a triage summary — NOT raw telemetry: a ranked findings array (read this first), per-operation anomaly flags, and bounded samples of spans/logs. Every lead carries a ready-to-run SQL string (drill_down_sql on standalone findings, each incident member shift, operations, spans, and log patterns; drill_all_sql on the spans/logs sections) that you paste VERBATIM into POST /v1/query to fetch the underlying rows and go deeper. Typical agent loop: GET /v1/services → POST /v1/diagnose → for any standalone finding, incident member shift, or anomalous operation, run its drill_down_sql via /v1/query. Timestamps are microseconds since the Unix epoch. The response is a map {results: {service: block}, errors: {service: message}} — partial results survive a single failing service.

POST/v1/diagnose

Authorization

AuthorizationBearer token (prefixed-api-key) · headerrequired

Request body

requiredapplication/json

from_tsinteger<int64> | null

Window start, **microseconds** since the Unix epoch (a 16-digit value, e.g. 1780000000000000). Seconds, milliseconds, and nanoseconds are rejected. OPTIONAL: omit both `from_ts` and `to_ts` for the last 15 minutes, the same default `sigiro diagnose` uses. Providing `to_ts` without `from_ts` is rejected — a window that ends somewhere with no start is ambiguous, and guessing one silently would answer a question nobody asked.

servicesstring[]required

Services to diagnose (1–10). Call `GET /v1/services` first to discover valid names.

to_tsinteger<int64> | null

Window end, microseconds since the Unix epoch. Must be > `from_ts`. Optional: defaults to now when `from_ts` is given alone.

Responses

200Per-service diagnosis blocks

errorsobjectrequired

Services whose diagnosis query failed, keyed by service name, with the error message. Empty when everything succeeded.

resultsobjectrequired

Successful diagnosis blocks, keyed by service name.

400Invalid request (e.g. timestamps not in microseconds, or to_ts <= from_ts)

401Missing or invalid bearer token

Request

curl -X POST "/v1/diagnose" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "from_ts": 1780000000000000,
  "services": [
    "checkout",
    "cart"
  ],
  "to_ts": 1780001800000000
}'

const response = await fetch("/v1/diagnose", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"from_ts\": 1780000000000000,\n  \"services\": [\n    \"checkout\",\n    \"cart\"\n  ],\n  \"to_ts\": 1780001800000000\n}"
});

import requests

response = requests.post(
    "/v1/diagnose",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"from_ts\": 1780000000000000,\n  \"services\": [\n    \"checkout\",\n    \"cart\"\n  ],\n  \"to_ts\": 1780001800000000\n}",
)

Response

{
  "errors": {
    "property1": "string",
    "property2": "string"
  },
  "results": {
    "property1": {
      "context": {
        "dependencies": [
          {
            "error_count": 0,
            "error_rate": 0.1,
            "service_name": "string",
            "span_count": 0
          }
        ],
        "dependents": [
          {
            "error_count": 0,
            "error_rate": 0.1,
            "service_name": "string",
            "span_count": 0
          }
        ],
        "deployment": "string",
        "first_seen": "string",
        "has_instance_id": true,
        "last_seen": "string",
        "namespace": "string",
        "pod_count": 0,
        "service_name": "string"
      },
      "coverage": {
        "has_logs": true,
        "has_metrics": true,
        "has_profiles": true,
        "has_spans": true,
        "log_template_count": 0,
        "metric_series_count": 0,
        "profile_sample_count": 0,
        "signals": [
          {
            "available": true,
            "reason": "string",
            "severity": "string",
            "signal_type": "string"
          }
        ],
        "span_count": 0
      },
      "error_traces_total": 0,
      "events": [
        {
          "description": "string",
          "detected_at": "string",
          "detected_at_us": 0,
          "event_type": "string"
        }
      ],
      "findings": [
        {
          "incident": {
            "deploy": {},
            "shifts": [
              {
                "after": 0.1,
                "before": 0.1,
                "drill_down_sql": "string",
                "entity": "string",
                "signal": "error_rate",
                "summary": "string",
                "ts_shift": 0,
                "ts_shift_iso": "string"
              }
            ],
            "started_at": 0,
            "started_at_iso": "string"
          },
          "kind": "incident",
          "severity": "critical",
          "summary": "string"
        }
      ],
      "gen_ai": [
        {
          "call_count": 0,
          "duration_p95_us": 0.1,
          "error_pct": 0.1,
          "finish_reasons": [
            {
              "count": 0,
              "reason": "string"
            }
          ],
          "input_tokens": 0,
          "model": "string",
          "operations": [
            "string"
          ],
          "output_tokens": 0,
          "system": "string"
        }
      ],
      "log_counters": [
        {
          "avg_value": 0.1,
          "label": "string",
          "max_value": 0.1,
          "min_value": 0.1,
          "pattern": "string",
          "pinned_zero": true,
          "samples": 0
        }
      ],
      "log_patterns": [
        {
          "count": 0,
          "drill_down_sql": "string",
          "error_count": 0,
          "example_body": "string",
          "first_seen": "string",
          "last_seen": "string",
          "pattern": "string",
          "sample_values": {},
          "severity_text": "string",
          "template_id": 0
        }
      ],
      "logs": {
        "drill_all_sql": "string",
        "sample": [
          {
            "attributes": {},
            "body": "string",
            "event_name": "string",
            "severity_text": "string",
            "span_id": "string",
            "timestamp": 0,
            "timestamp_iso": "string",
            "trace_id": "string"
          }
        ],
        "sampled_by": "string",
        "total": 0
      },
      "metrics": [
        {
          "avg": 0.1,
          "bucket": "string",
          "count": 0,
          "metric_name": "string",
          "p95": 0.1
        }
      ],
      "operation_summaries": [
        {
          "anomaly_reason": "string",
          "baseline_count": 0,
          "baseline_error_pct": 0,
          "baseline_p95_us": 0,
          "count": 0,
          "drill_down_sql": "string",
          "duration_p50_us": 0.1,
          "duration_p95_us": 0.1,
          "duration_p99_us": 0.1,
          "error_breakdown": [
            {
              "count": 0,
              "error_type": "string"
            }
          ],
          "error_count": 0,
          "error_pct": 0.1,
          "exemplar_error_trace_id": "string",
          "is_anomalous": true,
          "operation": "string",
          "span_name": "string"
        }
      ],
      "profiles": [
        {
          "function": "string",
          "profile_type": "string",
          "sample_count": 0,
          "total_value": 0,
          "unit": "string"
        }
      ],
      "service": "string",
      "spans": {
        "drill_all_sql": "string",
        "sample": [
          {
            "drill_down_sql": "string",
            "duration_us": 0,
            "end_ts": 0,
            "events": {},
            "is_error": true,
            "parent_span_id": "string",
            "span_attributes": {},
            "span_id": "string",
            "span_kind": 0,
            "span_name": "string",
            "start_iso": "string",
            "start_ts": 0,
            "status_code": 0,
            "status_message": "string",
            "trace_id": "string"
          }
        ],
        "sampled_by": "string",
        "total": 0
      },
      "window": {
        "from_iso": "string",
        "from_ts": 0,
        "to_iso": "string",
        "to_ts": 0
      }
    },
    "property2": {
      "context": {
        "dependencies": [
          {
            "error_count": 0,
            "error_rate": 0.1,
            "service_name": "string",
            "span_count": 0
          }
        ],
        "dependents": [
          {
            "error_count": 0,
            "error_rate": 0.1,
            "service_name": "string",
            "span_count": 0
          }
        ],
        "deployment": "string",
        "first_seen": "string",
        "has_instance_id": true,
        "last_seen": "string",
        "namespace": "string",
        "pod_count": 0,
        "service_name": "string"
      },
      "coverage": {
        "has_logs": true,
        "has_metrics": true,
        "has_profiles": true,
        "has_spans": true,
        "log_template_count": 0,
        "metric_series_count": 0,
        "profile_sample_count": 0,
        "signals": [
          {
            "available": true,
            "reason": "string",
            "severity": "string",
            "signal_type": "string"
          }
        ],
        "span_count": 0
      },
      "error_traces_total": 0,
      "events": [
        {
          "description": "string",
          "detected_at": "string",
          "detected_at_us": 0,
          "event_type": "string"
        }
      ],
      "findings": [
        {
          "incident": {
            "deploy": {},
            "shifts": [
              {
                "after": 0.1,
                "before": 0.1,
                "drill_down_sql": "string",
                "entity": "string",
                "signal": "error_rate",
                "summary": "string",
                "ts_shift": 0,
                "ts_shift_iso": "string"
              }
            ],
            "started_at": 0,
            "started_at_iso": "string"
          },
          "kind": "incident",
          "severity": "critical",
          "summary": "string"
        }
      ],
      "gen_ai": [
        {
          "call_count": 0,
          "duration_p95_us": 0.1,
          "error_pct": 0.1,
          "finish_reasons": [
            {
              "count": 0,
              "reason": "string"
            }
          ],
          "input_tokens": 0,
          "model": "string",
          "operations": [
            "string"
          ],
          "output_tokens": 0,
          "system": "string"
        }
      ],
      "log_counters": [
        {
          "avg_value": 0.1,
          "label": "string",
          "max_value": 0.1,
          "min_value": 0.1,
          "pattern": "string",
          "pinned_zero": true,
          "samples": 0
        }
      ],
      "log_patterns": [
        {
          "count": 0,
          "drill_down_sql": "string",
          "error_count": 0,
          "example_body": "string",
          "first_seen": "string",
          "last_seen": "string",
          "pattern": "string",
          "sample_values": {},
          "severity_text": "string",
          "template_id": 0
        }
      ],
      "logs": {
        "drill_all_sql": "string",
        "sample": [
          {
            "attributes": {},
            "body": "string",
            "event_name": "string",
            "severity_text": "string",
            "span_id": "string",
            "timestamp": 0,
            "timestamp_iso": "string",
            "trace_id": "string"
          }
        ],
        "sampled_by": "string",
        "total": 0
      },
      "metrics": [
        {
          "avg": 0.1,
          "bucket": "string",
          "count": 0,
          "metric_name": "string",
          "p95": 0.1
        }
      ],
      "operation_summaries": [
        {
          "anomaly_reason": "string",
          "baseline_count": 0,
          "baseline_error_pct": 0,
          "baseline_p95_us": 0,
          "count": 0,
          "drill_down_sql": "string",
          "duration_p50_us": 0.1,
          "duration_p95_us": 0.1,
          "duration_p99_us": 0.1,
          "error_breakdown": [
            {
              "count": 0,
              "error_type": "string"
            }
          ],
          "error_count": 0,
          "error_pct": 0.1,
          "exemplar_error_trace_id": "string",
          "is_anomalous": true,
          "operation": "string",
          "span_name": "string"
        }
      ],
      "profiles": [
        {
          "function": "string",
          "profile_type": "string",
          "sample_count": 0,
          "total_value": 0,
          "unit": "string"
        }
      ],
      "service": "string",
      "spans": {
        "drill_all_sql": "string",
        "sample": [
          {
            "drill_down_sql": "string",
            "duration_us": 0,
            "end_ts": 0,
            "events": {},
            "is_error": true,
            "parent_span_id": "string",
            "span_attributes": {},
            "span_id": "string",
            "span_kind": 0,
            "span_name": "string",
            "start_iso": "string",
            "start_ts": 0,
            "status_code": 0,
            "status_message": "string",
            "trace_id": "string"
          }
        ],
        "sampled_by": "string",
        "total": 0
      },
      "window": {
        "from_iso": "string",
        "from_ts": 0,
        "to_iso": "string",
        "to_ts": 0
      }
    }
  }
}