---
title: "Get orchestration queue stats"
method: GET
path: "/v1/projects/{project_id}/orchestrations/queue/stats"
tags: ["Orchestrations"]
---

# Get orchestration queue stats

`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`)

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.

## Response `200`

Queue stats snapshot

- QueueStats: A point-in-time snapshot of the orchestration run queue.
  - `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_depth` integer: 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_tasks` integer: Tasks currently claimed with a valid (unexpired) lease. Summed over the caller's own projects when the caller is project-scoped.
  - `oldest_queued_age_seconds` number, 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.
  - `claim_latency_ms` object: Claim-latency percentiles (time from a task becoming available to being claimed) over a rolling in-process window. `p50`/`p95` are `null` when no claim happened in the window, and for a project-scoped caller: the window is deployment-wide.
    - `p50` number, nullable
    - `p95` number, nullable
    - `window_seconds` integer

## Other responses

- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)