Orchestrations

Get orchestration queue stats

Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (queue_depth), how many are currently claimed with a valid lease (claimed_tasks), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window. The per-project breakdown is listed by GET /v1/projects/{project_id}/orchestrations/queue/stats/projects. Intended for admin/operator policies; guarded by orchestrations:GetQueueStats. Every figure is scoped to what the caller may see. A project-scoped caller gets queue_depth and claimed_tasks summed over their own projects, and null for oldest_queued_age_seconds and the claim_latency_ms percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.

get/v1/projects/{project_id}/orchestrations/queue/stats

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/orchestrations/queue/stats
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Response

Queue stats snapshot

driver'postgres' | 'sqs'

The active queue driver (ORCHESTRATION_QUEUE_DRIVER). Under sqs, oldest_queued_age_seconds is always null and the per-project listing is always empty — SQS exposes neither.

queue_depthinteger

Tasks waiting to be claimed now (unclaimed and past their available_at). Backoff-delayed tasks are excluded. Summed over the caller's own projects when the caller is project-scoped.

claimed_tasksinteger

Tasks currently claimed with a valid (unexpired) lease. Summed over the caller's own projects when the caller is project-scoped.

oldest_queued_age_secondsnumber nullable

Age in seconds of the oldest claimable-now task, or null when none are waiting. Also null for a project-scoped caller: the figure is deployment-wide.

Example response

{
  "driver": "postgres",
  "queue_depth": 12,
  "claimed_tasks": 3,
  "oldest_queued_age_seconds": 4.2,
  "claim_latency_ms": {
    "p50": 18,
    "p95": 240,
    "window_seconds": 300
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.