Sign in
Trading
Private

Retrieves the state of recent orders that have a specific label. This is useful for tracking orders that share the same label, which is helpful for managing related orders.

Results are filtered by currency and label. The response includes order details such as status, filled amount, remaining amount, and other order properties for all orders with the specified label.

Note: This method does not support the historical flag and only returns orders that closed within the last 30 minutes (same recency window as historical=false). This also applies to a trigger order and the order it creates upon triggering — once either has been closed for more than 30 minutes, it will no longer appear here, even though the same label was carried over between them. For orders older than that, use private/get_order_history_by_currency or private/get_order_history_by_instrument with historical=true.

📖 Related Article: Accessing Historical Trades and Orders Using API

Scope: trade:read

Try in API console

get/private/get_order_state_by_label

Query parameters

currency'BTC' | 'ETH' | 'USDC' | 'USDT' | 'EURR' required

Currency, i.e "BTC", "ETH", "USDC"

The currency symbol

labelstring required

user defined label for the order (maximum 64 characters)

Response

Success response

jsonrpc'2.0' required

The JSON-RPC version (2.0)

idinteger

The id that was sent in the request

Example response

{
  "result": [
    {
      "order_id": "ETH-100234",
      "instrument_name": "BTC-PERPETUAL",
      "creation_timestamp": 1536569522277,
      "last_update_timestamp": 1536569522277,
      "starbase_last_update_timestamp": 1536569522277000000,
      "block_trade": true,
      "trigger_order_id": "SLIB-370",
      "combo_order_id": "103148386169",
      "starbase_order_id": 103148386170,
      "app_name": "Example Application",
      "mmp_cancelled": true,
      "oto_order_ids": [
        "ETH-100234"
      ],
      "primary_order_id": "ETH-100234"
    }
  ]
}

Changes

Changed in 3 of the 7 revisions of this API.12

  • 6e5c000c82a81See the full diff
    • ○

      added the optional property result/items/starbase_client_order_id to the response with the 200 status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 430b3f0bc67c1See the full diff
    • ○

      removed the speed_bumped enum value from the result/items/order_state response property for the response status 200

      response-property-enum-value-removed

  • cc08850a8d921See the full diff
    • ●

      added the new speed_bumped enum value to the result/items/order_state response property for the response status 200

      response-property-enum-value-added