Runs

Read-only, cross-org run activity for the console's observability surface: list runs, inspect a single run's act DAG, pull a platform health snapshot, and inspect outbox delivery and Redis queue diagnostics.

Common responses

These responses apply across endpoints in this section unless an endpoint documents an additional response.

Status	Meaning	Body
`200`	Request succeeded.	Endpoint response object.
`201`	Resource created.	Created resource object.
`400`	Invalid request.	Error envelope.
`401`	Missing or invalid bearer token.	Error envelope.
`404`	Resource not found or not visible to the current organization.	Error envelope.

Runs

List runs

Cross-org run activity for the console's observability surface, paginated and sorted by `created_at` descending. Each row is enriched with the joined organization name, the display name (falling back to email) of the user who started the run, per-status act counts, and `prompt_summary` (the first 200 characters of the triggering message). `is_stuck` is true when the run's status is `running` and it hasn't been updated in 5 minutes — pass `stuck=true` to filter down to just those. `search` does a case-insensitive substring match against the organization name, the creating user's email, the prompt text, the run id, or the thread id.

GET/v1/admin/operations/runs

Query parameters

Name	Type	Required	Description
`status`	`string`	Optional	One of `running`, `awaiting`, `completed`, `cancelled`, `failed`. Repeatable (e.g. `status=running&status=awaiting`) to match any of the given statuses; omit to match all statuses.
`organizationId`	`string`	Optional	Restrict results to a single organization's UUID.
`createdFrom`	`string`	Optional	ISO 8601 datetime. Only include runs created at or after this instant.
`createdTo`	`string`	Optional	ISO 8601 datetime. Only include runs created at or before this instant.
`stuck`	`boolean`	Optional	`true` returns only stalled runs (`status=running` and no update for 5 minutes, i.e. `is_stuck: true`). `false` or omitted applies no stuck filter.
`search`	`string`	Optional	Case-insensitive substring match against organization name, creator email, prompt text, run id, or thread id.
`cursor`	`string`	Optional	Opaque pagination cursor returned in next_cursor of the previous response. Omit to start at the beginning.
`limit`	`number`	Optional	Maximum number of items to return. Default 20, max 100.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/admin/operations/runs?status=running&stuck=true&limit=20" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "7c9e6a10-2f3d-4b8e-9a11-6d5c7f8e2b34",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "organization_name": "Acme",
      "thread_id": "9d4f2c11-3a8b-4e6d-8c5a-1b7e9f3d6a20",
      "status": "running",
      "created_by_type": "user",
      "created_by_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "created_by_name": "Jane Cole",
      "created_at": "2026-07-24T14:02:10.000Z",
      "updated_at": "2026-07-24T14:09:47.000Z",
      "act_counts": {
        "blocked": 0,
        "ready": 1,
        "running": 1,
        "awaiting": 0,
        "completed": 2,
        "failed": 0,
        "cancelled": 0
      },
      "is_stuck": false,
      "error_summary": null,
      "failure_reason": null,
      "prompt_summary": "Summarize the Q2 churn report and flag any accounts at risk of downgrading."
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 1
}

Get run

Return a single run with the same enriched fields as the list, plus its full act DAG (`acts`) and a `usage` placeholder. Acts carry their `key`, `status`, `depends_on` list, assignment (`assigned_to_type`/`assigned_to_id`), `attempts`, `error`, and timing fields (`started_at`, `completed_at`, `heartbeat_at`, `created_at`). `usage` is always `null` for now — per-run token/cost aggregation arrives in a later plan.

GET/v1/admin/operations/runs/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The run's UUID.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/admin/operations/runs/7c9e6a10-2f3d-4b8e-9a11-6d5c7f8e2b34 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Run not found.	`{ error, code: 'not_found' }`
`403`	Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.	`{ error, code, request_id }`

200 OKjson

{
  "id": "7c9e6a10-2f3d-4b8e-9a11-6d5c7f8e2b34",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "organization_name": "Acme",
  "thread_id": "9d4f2c11-3a8b-4e6d-8c5a-1b7e9f3d6a20",
  "status": "running",
  "created_by_type": "user",
  "created_by_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "created_by_name": "Jane Cole",
  "created_at": "2026-07-24T14:02:10.000Z",
  "updated_at": "2026-07-24T14:09:47.000Z",
  "act_counts": {
    "blocked": 0,
    "ready": 1,
    "running": 1,
    "awaiting": 0,
    "completed": 2,
    "failed": 0,
    "cancelled": 0
  },
  "is_stuck": false,
  "error_summary": null,
  "failure_reason": null,
  "prompt_summary": "Summarize the Q2 churn report and flag any accounts at risk of downgrading.",
  "acts": [
    {
      "id": "3b6e4a10-8f2d-4c91-9a77-1e5c8d3f9b24",
      "key": "classify_intent",
      "status": "completed",
      "depends_on": [],
      "assigned_to_type": "system",
      "assigned_to_id": null,
      "attempts": 1,
      "error": null,
      "started_at": "2026-07-24T14:02:11.000Z",
      "completed_at": "2026-07-24T14:02:13.000Z",
      "heartbeat_at": "2026-07-24T14:02:13.000Z",
      "created_at": "2026-07-24T14:02:10.000Z"
    }
  ],
  "usage": null
}

Health

Get health snapshot

Point-in-time platform health snapshot for the console's observability surface, meant to be polled rather than streamed. `verdict` is a single overall read (`operational`, `degraded`, or `down`) with a human-readable `reason`. `golden_signals` carries success rate over the last 1 and 24 hours, run throughput per minute over the last hour, time-to-first-token p50/p95 in milliseconds over the last 24 hours, and a `failing_now` count of runs currently in a failed state; any rate or latency figure is `null` when there isn't enough data to compute it. `runs` and `approvals` are current counts (running, awaiting, completed/failed/cancelled in the last 24 hours, stuck runs, and pending approvals with the age in seconds of the oldest one). `pipeline` reports the outbox delivery state (`flowing`, `delayed`, or `stalled`) along with pending and poison message counts and the oldest pending message's age in seconds. `top_failure_reasons` ranks the most common failure reasons over the last 24 hours by count. `incidents` is an impact-first list of active issues, each with a `severity` (`warning` or `danger`), the user-facing `impact`, the underlying `cause`, the `affected_scope`, and an `action_href` deep link into the console.

GET/v1/admin/operations/health/snapshot

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/admin/operations/health/snapshot \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.	`{ error, code, request_id }`

200 OKjson

{
  "verdict": {
    "level": "degraded",
    "reason": "9 runs failed in the last 24 hours."
  },
  "golden_signals": {
    "success_rate1h": 0.91,
    "success_rate24h": 0.97,
    "runs_started_per_min1h": 4.2,
    "ttft_p50_ms": 820,
    "ttft_p95_ms": 2400,
    "failing_now": 9
  },
  "runs": {
    "running": 12,
    "awaiting": 2,
    "completed24h": 341,
    "failed24h": 9,
    "cancelled24h": 4,
    "stuck": 0
  },
  "approvals": {
    "pending": 2,
    "oldest_age_seconds": 187
  },
  "pipeline": {
    "state": "flowing",
    "pending": 5,
    "poison": 0,
    "oldest_pending_age_seconds": 12
  },
  "top_failure_reasons": [
    {
      "reason": "tool_timeout",
      "count": 5
    },
    {
      "reason": "model_error",
      "count": 3
    },
    {
      "reason": "rate_limited",
      "count": 1
    }
  ],
  "incidents": [
    {
      "severity": "warning",
      "impact": "9 runs failed in the last 24 hours.",
      "cause": "Most common: tool_timeout.",
      "affected_scope": "9 runs",
      "action_href": "/runs?status=failed"
    }
  ],
  "generated_at": "2026-07-25T18:32:04.000Z"
}

Diagnostics

List outbox messages

Cross-org view of the `run_outbox` command-delivery table, for engineer-only diagnostics. Each row is enriched with the joined organization name. `status` is `pending` (not yet delivered) or `sent`. Use `minAttempts` to find poison messages — commands that have retried past the poison threshold, e.g. `minAttempts=5`.

GET/v1/admin/operations/outbox

Query parameters

Name	Type	Required	Description
`status`	`string`	Optional	One of `pending` or `sent`. Omit to match both.
`stream`	`string`	Optional	Exact match against the stream name.
`minAttempts`	`number`	Optional	Only include messages with at least this many delivery attempts. For example, `minAttempts=5` surfaces poison messages retrying past the poison threshold.
`cursor`	`string`	Optional	Opaque pagination cursor returned in next_cursor of the previous response. Omit to start at the beginning.
`limit`	`number`	Optional	Maximum number of items to return. Default 20, max 100.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/admin/operations/outbox?status=pending&minAttempts=5" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "b3f1c2d4-9a7e-4f21-8b3c-5e6d7f8a9b10",
      "stream": "run.start",
      "tenant_id": "a1b2c3d4-5e6f-4789-9abc-def012345678",
      "organization_name": "Acme Corp",
      "status": "pending",
      "attempts": 6,
      "last_error": "connection reset by peer",
      "created_at": "2026-07-25T18:20:00.000Z",
      "sent_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 1
}

Get queue stats

Redis stream and consumer-group stats for the platform's message bus, for engineer-only diagnostics. `pending` and each consumer's `pending`/`idle_ms` (milliseconds since that consumer's last activity) are the live signals for spotting a stalled or stuck worker. `lag` is currently always `0` — a limitation of the installed Redis client version — and should not be relied on.

GET/v1/admin/operations/queues

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/admin/operations/queues \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "stream": "run.start",
      "group": "run.start-workers",
      "length": 42,
      "pending": 3,
      "lag": 0,
      "consumers": [
        {
          "name": "worker-1",
          "pending": 2,
          "idle_ms": 1500
        },
        {
          "name": "worker-2",
          "pending": 1,
          "idle_ms": 400
        }
      ]
    }
  ]
}