Appearance
Get spool stats
GET /spools/{spool}/stats
The live view of the spool: the rollup, queue count and message counts summed across every queue with total being the cap-enforced count, plus one name-ordered page of its queues, each with its settings and counts. Everything comes from one snapshot, not a live read. The page takes the listing's parameters; queue selects named queues, and a name the spool lacks is absent from the page, not an error.
Sample
sh
curl -X GET "$SPOOLER_API/spools/<spool>/stats" \
-H "Authorization: Bearer $SPOOLER_KEY"Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
spool | path | IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$ | yes | The spool name. |
queue | query | array | no | Keep only these queues, repeatable; absent keeps every queue. |
limit | query | integer, 1–1,000, default 100 | no | Max queues per page. |
after | query | Cursor, 1–256 chars | no | Resume the page just past this cursor (the previous page's next); absent starts at the first queue. |
match | query | string | no | Keep only queue names matching this RE2 regular expression, unanchored (anchor with ^ and $ for an exact match); absent keeps everything. Pagination walks matching names only. |
Responses
| Status | Description |
|---|---|
200 | The spool's rollup and one page of its queues. |
400 | The request is malformed; the kind names the problem. |
401 | The API key is missing or not recognized. |
402 | The account is suspended. |
403 | A plan limit refuses the operation; the kind names it. A 403 without a kind, on any operation, means the API key is blocked. |
404 | The spool or queue does not exist; the kind says which. |
429 | The per-account request rate cap is exceeded. The body names the kind (rate_limited); the wait is the Retry-After header and is not repeated in the body. Headers are as structured as the body, and this one is the header HTTP defines for a wait. |
503 | The spool is momentarily unavailable. |
200 body shape
The shape, not a sample: values are the wire types;
?marks an optional field.
jsonc
{
// The number of queues on the spool, whatever the page selects.
queueCount: integer,
// Message counts rolled up across every queue; total is the
// cap-enforced count, in-flight sends included.
stats: {
// Stored messages on the queue, every state counted. Can transiently
// exceed the per-state sum: the difference is messages in transit
// between states.
total: integer,
// The logical payload bytes of the counted messages.
dataBytes: integer,
// Scheduled for a future delivery time; not yet available to receive.
delayed: integer,
// Available to receive now.
visible: integer,
// Delivered and awaiting ack; auto-nacked back to visible when the
// lease times out.
pending: integer,
// Failed: retries exhausted or failed explicitly, waiting for recover
// or discard.
failed: integer,
// Held back because the service could not read their payload. No
// delivery attempt is charged and no retry is consumed; the read is
// retried automatically, so a non-zero count reflects a service-side
// condition, not a consumer one.
unavailable: integer,
// Messages appended since the last restart; duplicates suppressed by
// dedup are not counted. A cumulative counter that resets on restart:
// compute rates from deltas clamped at zero.
addedTotal: integer,
// Messages acked since the last restart; same counter semantics as
// addedTotal.
ackedTotal: integer,
// Messages nacked since the last restart; same counter semantics as
// addedTotal.
nackedTotal: integer,
// Deliveries released (returned without spending a retry) since the
// last restart; same counter semantics as addedTotal.
releasedTotal: integer,
// Messages failed since the last restart; same counter semantics as
// addedTotal.
failedTotal: integer,
// Messages explicitly discarded since the last restart; same counter
// semantics as addedTotal.
discardedTotal: integer,
// Messages discarded by retention since the last restart; same
// counter semantics as addedTotal. A growing rate means messages age
// out before consumers reach them.
expiredTotal: integer,
},
// One page of the selected queues, each with its stats.
queues: {
// One page of the selected queues, ordered by name in byte order.
items: [
{
// The queue's name.
//
// Length: 1–63 chars
// Pattern: ^[A-Za-z0-9_:-]+$
name: string,
// The time of the queue creation; a recreation under the same
// name gets a new one, so it identifies the queue across reuse of
// the name.
createdAt: string,
// The queue's lifecycle state, as on Queue.
state: "active" | "draining" | "deleting",
// The queue's current settings, as applied.
settings: {
// Seconds before an unacked delivery is auto-nacked; 0 means
// the timeout is disabled.
leaseTimeoutSeconds: integer,
// Redeliveries before a message is failed; 0 means no retries.
maxRetries: integer,
// Seconds a dedup key is remembered; 0 means dedup is disabled.
dedupWindowSeconds: integer,
// Seconds a message is kept before it is discarded, as set. At
// least a minute today; 0 is reserved to mean no expiry, so
// treat it as such.
retentionSeconds: integer,
// The retention actually enforced: retentionSeconds bounded by
// the plan's retention limit. The clock starts when a message
// first becomes visible (a send delay does not count) and keeps
// running: a leased message is not expired while held, but
// nack, release and a lease timeout return it with the clock as
// it was. Failing restarts the clock, and so does recovering. A
// failed message expires like any other.
effectiveRetentionSeconds: integer,
// The cap on the rate Recv hands out messages; all zero means
// no limit.
recvRateLimit: {
// The token-bucket refill interval in microseconds; 0 means
// no limit.
intervalMicros: integer,
// The bucket size; 0 means no limit.
burst: integer,
},
},
// Message counts, from the same snapshot as the rollup.
stats: {
// Stored messages on the queue, every state counted. Can
// transiently exceed the per-state sum: the difference is
// messages in transit between states.
total: integer,
// The logical payload bytes of the counted messages.
dataBytes: integer,
// Scheduled for a future delivery time; not yet available to
// receive.
delayed: integer,
// Available to receive now.
visible: integer,
// Delivered and awaiting ack; auto-nacked back to visible when
// the lease times out.
pending: integer,
// Failed: retries exhausted or failed explicitly, waiting for
// recover or discard.
failed: integer,
// Held back because the service could not read their payload.
// No delivery attempt is charged and no retry is consumed; the
// read is retried automatically, so a non-zero count reflects a
// service-side condition, not a consumer one.
unavailable: integer,
// Messages appended since the last restart; duplicates
// suppressed by dedup are not counted. A cumulative counter
// that resets on restart: compute rates from deltas clamped at
// zero.
addedTotal: integer,
// Messages acked since the last restart; same counter semantics
// as addedTotal.
ackedTotal: integer,
// Messages nacked since the last restart; same counter
// semantics as addedTotal.
nackedTotal: integer,
// Deliveries released (returned without spending a retry) since
// the last restart; same counter semantics as addedTotal.
releasedTotal: integer,
// Messages failed since the last restart; same counter
// semantics as addedTotal.
failedTotal: integer,
// Messages explicitly discarded since the last restart; same
// counter semantics as addedTotal.
discardedTotal: integer,
// Messages discarded by retention since the last restart; same
// counter semantics as addedTotal. A growing rate means
// messages age out before consumers reach them.
expiredTotal: integer,
},
}
],
// Cursor of the following page (pass as after); absent when this page
// ends the selection.
//
// Length: 1–256 chars
next?: string,
},
}429 headers
| Header | Description |
|---|---|
Retry-After | Seconds until the next request is admitted, whole and at least 1; always the delay-seconds form, never an HTTP-date. |