Describe a spool

Last updated Oct 12, 2026

GET /spools/{spool}

The spool with its stats: its queue count and message counts summed across every queue, total being the cap-enforced count. The cumulative counters are the spool's own and keep counting deleted queues, so they are not a sum over the queues the listing shows. One snapshot, not a live read.

Sample

curl -X GET "$SPOOLER_API/spools/<spool>" \
  -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.

Responses

Status	Description
200	The spool.
400	The request is malformed; the kind names the problem.
401	The API key is missing or not recognized; the kind is unauthenticated.
402	The account is suspended; the kind is account_suspended.
403	The operation is refused; the kind names why: a plan limit (queue_limit, retention_limit), or account_blocked on any operation when the account is on an abuse hold.
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.

{
  // The spool's name.
  //
  // Length:  1–63 chars
  // Pattern: ^[A-Za-z0-9_:-]+$
  name: string,

  // The number of queues on the spool.
  queueCount: integer,

  // Message counts summed across every queue; total is the cap-enforced
  // count, in-flight sends included. The cumulative counters keep
  // counting deleted queues.
  stats: {
    // When the counts were sampled. Equal values mean one snapshot.
    sampledAt: string,

    // When the cumulative counters started; they were zero at this
    // instant. It is the spool's last opening on its serving member, or
    // the queue's creation when the queue is newer than that. A restart
    // or failover moves it and starts the counters over from zero, so
    // compute rates only between samples with equal startedAt.
    startedAt: string,

    // 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 startedAt; duplicates suppressed by dedup
    // are not counted. A cumulative counter: zero at startedAt and never
    // lowered until a restart or failover moves startedAt.
    addedTotal: integer,

    // Messages acked; same counter semantics as addedTotal.
    ackedTotal: integer,

    // Messages nacked; same counter semantics as addedTotal.
    nackedTotal: integer,

    // Deliveries released (returned without spending a retry); same
    // counter semantics as addedTotal.
    releasedTotal: integer,

    // Messages failed; same counter semantics as addedTotal.
    failedTotal: integer,

    // Messages explicitly discarded; same counter semantics as
    // addedTotal.
    discardedTotal: integer,

    // Messages discarded by retention; same counter semantics as
    // addedTotal. A growing rate means messages age out before consumers
    // reach them.
    expiredTotal: integer,
  },
}

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.