Stack operations

Stack operations

Get All Node Stacks

GET /stacks

Returns all stacks associated with currently registered node badges.

Response Status Codes

• 200 OK: Successfully retrieved stacks

• 500 Internal Server Error: Failed to retrieve stacks from state manager

Response

[
  {
    "owner_address": "0x123...",
    "stack_small_id": 1,
    "stack_id": "stack-123",
    "task_small_id": 10,
    "selected_node_id": 123,
    "num_compute_units": 1000,
    "price": 10000,
    "already_computed_units": 500,
    "in_settle_period": false,
    "total_hash": "0x...",
    "num_total_messages": 50
  }
]

Response Fields

• owner_address (string): Address of the stack owner

• stack_small_id (integer): Unique small integer identifier for the stack

• stack_id (string): Unique string identifier for the stack

• task_small_id (integer): Small integer identifier of the associated task

• selected_node_id (integer): Identifier of the selected node for computation

• num_compute_units (integer): Total number of compute units in this stack

• price (integer): Price of the stack in smallest currency unit

• already_computed_units (integer): Number of compute units already processed

• in_settle_period (boolean): Whether the stack is currently in the settle period

• total_hash (string): Joint concatenation of Blake2b hashes of processed payload/response pairs

• num_total_messages (integer): Number of payload requests received for this stack

Get Node Stacks

GET /stacks/:id

Returns all stacks for a specific node identified by its small ID.

Parameters

• id (path, integer): Node small ID

Response Status Codes

• 200 OK: Successfully retrieved stacks

• 500 Internal Server Error: Failed to retrieve stacks from state manager

Response

Same format as Get All Node Stacks, filtered for the specified node.

Get Almost Filled Stacks

GET /almost_filled_stacks/:fraction

Returns all stacks that are filled above a specified fraction threshold for all registered nodes.

Parameters

• fraction (path, float): Fill threshold (0.0 to 100.0) to filter stacks

Response Status Codes

• 200 OK: Successfully retrieved stacks

• 500 Internal Server Error: Failed to retrieve stacks from state manager

Response

Same format as Get All Node Stacks, filtered by the fill threshold.

Example Error Response

{
  "error": "Failed to get all almost filled stacks"
}

Get Node Almost Filled Stacks

GET /almost_filled_stacks/:id/:fraction

Returns all stacks that are filled above a specified fraction threshold for a specific node.

Parameters

• id (path, integer): Node small ID

• fraction (path, float): Fill threshold (0.0 to 100.0) to filter stacks

Response Status Codes

• 200 OK: Successfully retrieved stacks

• 500 Internal Server Error: Failed to retrieve stacks from state manager

Response

Same format as Get All Node Stacks, filtered by both node ID and fill threshold.

Example Error Response

{
  "error": "Failed to get node almost filled stacks"
}

Notes

• The fill threshold represents the percentage of compute units already processed

• A stack is considered "filled" when already_computed_units / num_compute_units >= fraction

• The fraction parameter should be between 0.0 and 100.0