--- title: "Get Engine Performance" method: GET path: "/v1/analytics/performance/engine" tags: ["Analytics", "Analytics - Performance"] --- # Get Engine Performance `GET /v1/analytics/performance/engine` Get engine performance metrics over time. Query profiling data logged by the engine's profiling infrastructure. All queries are automatically filtered to your namespace. **Time Range:** - Specify `hours` for recent history (e.g., `hours=24` for last 24 hours) - OR specify `start_date` and `end_date` for custom range - Defaults to last 24 hours if neither provided **Grouping:** - `minute`: High-resolution (for short time ranges) - `hour`: Standard resolution (default) - `day`: For longer time ranges - `week`, `month`: For historical trends **Response:** - Time-series metrics (avg, p50, p95, p99 latencies) - Summary statistics across the entire time range - All latencies in milliseconds **Example:** ```bash GET /v1/analytics/performance/engine?hours=24&group_by=hour ``` ## Query parameters - `hours` integer, nullable — Hours of history (alternative to date range) - `start_date` string, date-time, nullable — Start date for time range - `end_date` string, date-time, nullable — End date for time range - `group_by` string — Time grouping (minute, hour, day, week) ## Response `200` Successful Response - EnginePerformanceResponse — Response for engine performance query. - `time_range` ApiAnalyticsModelsTimeRange, required — Time range for analytics queries. - `start` string, date-time, required — Start time (UTC) - `end` string, date-time, required — End time (UTC) - `metrics` PerformanceMetric[], required — Time-series performance metrics - `time_bucket` string, date-time, required — Time bucket for this metric (hour, day, etc.) - `execution_count` integer, required — Number of executions in this period - `avg_latency_ms` number, required — Average latency in milliseconds - `p50_latency_ms` number, required — 50th percentile (median) latency - `p95_latency_ms` number, required — 95th percentile latency - `p99_latency_ms` number, required — 99th percentile latency - `max_latency_ms` number, required — Maximum latency observed - `summary` PerformanceSummary — Summary statistics for performance. - `total_executions` integer — Total number of executions - `avg_latency_ms` number — Average latency - `p50_latency_ms` number — Median latency - `p95_latency_ms` number — 95th percentile latency - `p99_latency_ms` number — 99th percentile latency - `max_latency_ms` number — Maximum latency - `total_time_seconds` number — Total time spent across all executions - `service_health` ServiceHealth — Per-namespace service-health dimensions (ADM-18, BACKE-3527). Honest health is the whole point of this block. Every dimension whose source is not wired returns None with the reason stated in its Field description. None means "not yet computed here", never zero: a fabricated 0.0 or 1.0 would read as perfect health and hide the gap. The rollup-backed dimensions (availability, degraded_rate, partial_rate, and — BACKE-3527 — timeout_rate, throttle_rate) are READ from the namespace rollup doc the signals sweep already writes (api/documents/signals_rollup.py, namespace_rollup_doc). This block never recomputes the rollup. dependency_health remains unwired (None) until a per-dependency registry exists. - `availability` number, nullable — Success rate over the latest rollup window: 1 - failed_rate from the namespace `_signals` rollup doc. None = no rollup doc for the window yet, not zero. - `degraded_rate` number, nullable — Fraction of executions that degraded, read from the namespace rollup doc's degraded_rate. None = not yet computed here, not zero. - `partial_rate` number, nullable — Fraction of executions that degraded but still returned results, from the rollup doc's partial_rate. None = not yet computed here, not zero. - `timeout_rate` number, nullable — Fraction of executions that hit a stage-budget ceiling (a stage cancelled/skipped for exceeding its hard latency ceiling), read from the namespace rollup doc's timeout_rate (BACKE-3527). None = no rollup doc for the window yet, or the doc predates the flag; not zero. A real 0.0 means no timeouts in the window. - `throttle_rate` number, nullable — Fraction of executions rejected by a credit/quota cap (the UnauthorizedError-on-cap class), read from the namespace rollup doc's throttle_rate (BACKE-3527). None = no rollup doc for the window yet, or the doc predates the flag; not zero. A real 0.0 means no cap rejections in the window. - `dependency_health` object, nullable — Per-dependency status (shard / embedding / redis / object-store). None = no readable per-dependency health registry exists yet; the BACKE-3493 ownership registry is not present in this codebase, so there is nothing to join per-tenant. Not an empty object. - `window_end_ts` number, nullable — Epoch seconds of the rollup window the rates were read from. None when no rollup doc was found. - `freshness_seconds` integer — Metrics-availability budget: these health dimensions reflect state within this many seconds (the ADM-18 'within 2 minutes' guarantee). Rollup docs are folded at the signals sweep cadence. - `reconciliation` string — Stated tolerance for how these counts tie to request logs. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error ## Changes - **2026-08-24** `b40f559d564a` — 1 info - added the optional property `service_health` to the response with the `200` status - **2026-08-09** `5d4c905106b4` — 1 info - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API [Change history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/analytics/performance/engine/get.md) --- [API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/3775e0b36ee1/schema)