Skip to main content
GET
Read one job group's rollup

Authorizations

Authorization
string
header
required

Authorization: Bearer hk_live_... for live keys or Authorization: Bearer hk_test_... for test-mode keys. hk_test_ keys resolve real public catalog metadata but return deterministic committed fixtures, never call inference, and never mutate live credits. This is the only transport for the credential: the x-api-key alias once documented was removed in 0.2.0, because the edge authorizer reads Authorization as its single identity source and a request on any other header is refused before it is authenticated.

Never accepted on a dashboardJwt operation, and there are no exceptions. GET /v1/usage and GET /v1/limits briefly declared both schemes (0.8.0); that was withdrawn in 0.8.1 because no deployed route could honor it — both operations are served by the control-plane API, whose authorizer verifies a Cognito token and refuses an hk_live_ credential on shape, and the customer API does not route either path. An API-key holder reads its balance and reservation from QuoteResponse, which carries balance_credits and reserved_credits on every quote. Every operation in this document takes one scheme or the other and refuses the wrong one as unauthenticated.

Path Parameters

group_id
string
required

Opaque, server-generated job group identifier.

Maximum string length: 40
Pattern: ^grp_[A-Za-z0-9]{16,32}$

Response

The group and its members.

One group's rollup. member_count is how many members the confirm set out to create; members is how many exist, which is fewer only while the group is pending (or after it was abandoned part way). credits_reserved is what the group still holds against the balance — the reservations of members not yet terminal; credits_settled is what it has been charged, job members and cache reads together; credits_released is what came back from members that failed, were cancelled, or settled below their ceiling. None of the three is a bill: each job member carries its own figures, and the ledger is the record.

group_id
string
required

Opaque, server-generated job group identifier.

Maximum string length: 40
Pattern: ^grp_[A-Za-z0-9]{16,32}$
status
enum<string>
required

pending while a confirm is still fanning out (or died doing so); complete once every member landed; abandoned once the sweeper returned a pending group's reservations past its deadline. A cancelled group is complete with cancelled members.

Available options:
pending,
complete,
abandoned
quote_id
required

The quote this group confirmed, or null for a single-episode submission.

Maximum string length: 40
Pattern: ^qte_[A-Za-z0-9]{16,32}$
member_count
integer
required
Required range: x >= 1
members
object[]
required
Maximum array length: 100

One member of a group — a job, or a settled cache read. kind discriminates.

member_counts
object
required

How many members are in each job state, plus how many were settled cache reads (which have no state — they were delivered at confirm). The nine sum to member_count on a complete group.

credits_reserved
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
credits_settled
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
credits_released
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
created_at
string<date-time>
required
completion_deadline
string<date-time>
required

Past this, a still-pending group is swept.

completed_at
required

An ISO 8601 timestamp, or null.

abandoned_at
required

An ISO 8601 timestamp, or null.