Get Grid Bot Detail

Retrieve comprehensive details for a specific futures grid bot, including configuration, status, PnL metrics, position info, margin balances, and timestamps.

info

• bot_id:
  Obtained from the Create Futures Grid Bot response or bot listing endpoints.

• PnL fields:
  pnl is the total cumulative PnL. grid_profit covers only grid trade profit. realised_pnl and unrealised_pnl break down the total PnL further.

• Rate limit:
  10 requests per second per UID.

HTTP Request

POST/v5/fgridbot/detail

Request Parameters

Parameter	Required	Type	Comments
bot_id	true	string	Bot ID to query

Response Parameters

Parameter	Type	Comments
status_code	integer	0 = success, non-zero = error
debug_msg	string	Debug message (testnet only)
detail	object	Grid bot detail object (see below)
> bot_id	string	Unique grid bot ID
> symbol	string	Trading pair (e.g. BTCUSDT)
> base_token	string	Base coin (e.g. BTC)
> quote_token	string	Quote coin (e.g. USDT)
> status	string	Bot lifecycle status: Unspecified, Rejected, New, Initializing, Running, Cancelling, Completed, Await activation
> grid_mode	string	Strategy direction: Unspecified, Neutral, Long, Short
> grid_type	string	Grid spacing type: Unspecified, Arithmetic, Geometric
> min_price	string	Grid lower price bound (decimal string)
> max_price	string	Grid upper price bound (decimal string)
> cell_number	integer	Number of grid levels
> leverage	string	Initial leverage multiplier (e.g. "5" means 5x)
> real_leverage	string	Actual effective leverage (e.g. "4.8" means 4.8x)
> total_investment	string	Total investment including additional top-ups (decimal string)
> total_value	string	Total position value in quote currency (decimal string)
> current_position	string	Current position size in contracts (decimal string)
> pnl	string	Cumulative total PnL in quote currency (decimal string)
> pnl_per	string	PnL as percentage of total investment (e.g. "0.0505" means 5.05%)
> grid_profit	string	Profit from grid trades only (decimal string)
> grid_apr	string	Annualized grid profit rate as percentage (e.g. "0.365" means 36.5% APR)
> total_apr	string	Total annualized profit rate as percentage (e.g. "0.42" means 42% APR)
> realised_pnl	string	Cumulative realized PnL (decimal string)
> unrealised_pnl	string	Unrealized PnL based on mark price (decimal string)
> funding_fee	string	Cumulative funding fee (decimal string, positive = received, negative = paid)
> position_balance	string	Position margin balance (decimal string)
> available_balance	string	Available (free) margin balance (decimal string)
> total_order_balance	string	Margin locked in pending orders (decimal string)
> equity	string	Running equity value (decimal string)
> last_price	string	Current last traded price
> mark_price	string	Current mark price
> liquidation_price	string	Estimated liquidation price
> stop_loss_per	string	Stop-loss as percentage (e.g. "0.1" means 10%)
> take_profit_per	string	Take-profit as percentage (e.g. "0.2" means 20%)
> stop_loss_price	string	Stop-loss price
> take_profit_price	string	Take-profit price
> tp_sl_type	string	TP/SL trigger mode: Unspecified, Both %, Both price, TP price+SL %, TP %+SL price
> entry_price	string	Entry trigger price
> real_close_price	string	Actual price when bot was stopped
> min_price_precision	string	Minimum price precision for the symbol
> tick_size	string	Tick size — minimum price increment
> trailing_stop_per	string	Trailing stop callback as percentage (e.g. "0.05" means 5%)
> trailing_stop_exit_equity	string	Equity at trailing stop exit (decimal string)
> close_reason	string	Unspecified, Init failure, User stopped, Take-profit triggered, Insufficient order balance, Liquidation, Contract delisted, FBU trigger failed, Asset transfer failed, Stop-loss triggered, Reduce-only, Risk limit, System anomaly — fallback stop, Close price worse than bankruptcy price, User banned, Neutral grid hit top price, Neutral grid hit bottom price, CopyTrade master stopped, CopyTrade follower insufficient balance, CopyTrade bad entry timing, Negative arbitrage, Trailing stop, Compliance clearance, ADL (Auto-Deleveraging)
> bot_close_code	string	Unspecified, Failed initiation, Canceled manually by user, Canceled automatically (other), Canceled by take-profit trigger, Canceled by stop-loss trigger, Canceled by liquidation, DCA reached max investment, User account banned, Neutral grid hit top price, Neutral grid hit bottom price, Martingale round take-profit triggered, Symbol delisted, Negative arbitrage, Trailing stop exit, Compliance clearance, ADL (Auto-Deleveraging)
> futures_pos_side	string	Unspecified, Short position, Long position
> arbitrage_num	integer	Total arbitrage (grid fill) count
> arbitrage_num_24	integer	Arbitrage count in last 24 hours
> min_profit	string	Minimum per-grid profit rate as percentage
> max_profit	string	Maximum per-grid profit rate as percentage
> move_up_price	string	Move-up max price for grid shifting
> move_down_price	string	Move-down min price for grid shifting
> curr_min_price	string	Current effective minimum grid price
> curr_max_price	string	Current effective maximum grid price
> i_m_rate	string	Initial margin rate as decimal ratio (e.g. "0.1" = 10%)
> m_m_rate	string	Maintenance margin rate as decimal ratio (e.g. "0.005" = 0.5%)
> account_type	string	Unspecified, Derivative account, Unified margin account, Account upgrading, Spot account, UTA (Unified Trading Account), Fund account
> allow_follow	integer	Whether copy-trading is allowed: 1 yes, 0 no
> follow_num	integer	Number of users copying this bot
> copy_trade_is_master	boolean	Whether this bot is a copy-trade master
> copy_trade_follower_num	string	Number of copy-trade followers
> used_reward_amount	string	Total voucher/reward amount used
> used_reward_id	string	ID of the first insurance voucher used
> init_bonus	string	Initial bonus amount
> used_bonus_amount	string	Bonus amount already consumed
> settlement_assets	string	Settlement asset info
> cum_withdrew_amount	string	Cumulative withdrawn margin amount
> current_profit	string	Current running PnL (decimal string)
> current_per	string	Current running PnL as percentage (e.g. "0.032" means 3.2%)
> taker_fee_rate	string	Taker fee rate as decimal ratio (e.g. "0.0006" = 0.06%)
> maker_fee_rate	string	Maker fee rate as decimal ratio (e.g. "0.0001" = 0.01%)
> operation_time	string	Milliseconds since bot creation
> create_time	string	Bot creation timestamp (Unix milliseconds)
> modify_time	string	Last update timestamp (Unix milliseconds)
> end_time	string	Bot end timestamp (Unix milliseconds), 0 if still running
> adl_rank_indicator	integer	ADL (Auto-Deleveraging) rank indicator

---

Request Example

POST /v5/fgridbot/detail HTTP/1.1
Host: api-testnet.bybit.com
X-BAPI-SIGN: XXXXX
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1672211928338
X-BAPI-RECV-WINDOW: 5000
Content-Type: application/json

{
    "bot_id": "612330315406398322"
}

Response Example

{
    "retCode": 0,
    "retMsg": "success",
    "result": {
        "status_code": 0,
        "detail": {
            "bot_id": "612330315406398322",
            "symbol": "BTCUSDT",
            "status": "FUTURE_GRID_STATUS_COMPLETED",
            "base_token": "BTC",
            "quote_token": "USDT",
            "min_price": "230000",
            "max_price": "800000",
            "cell_number": 88,
            "grid_type": "FUTURE_GRID_TYPE_GEOMETRIC",
            "grid_mode": "FUTURE_GRID_MODE_LONG",
            "stop_loss_per": "",
            "take_profit_per": "0.28",
            "real_leverage": "6",
            "total_investment": "950",
            "total_value": "",
            "current_position": "",
            "arbitrage_num": 0,
            "arbitrage_num_24": 0,
            "pnl": "0",
            "pnl_per": "0.0000",
            "grid_profit": "0",
            "grid_apr": "0",
            "total_apr": "0",
            "last_price": "",
            "liquidation_price": "",
            "realised_pnl": "",
            "unrealised_pnl": "",
            "funding_fee": "",
            "position_balance": "",
            "available_balance": "",
            "total_order_balance": "",
            "close_reason": "F_GRID_BOT_STOP_TYPE_TRIGGER_FBU_FAIL",
            "allow_follow": 1,
            "operation_time": "1110",
            "create_time": "1774506909414",
            "modify_time": "1774506910524",
            "end_time": "1774506910522",
            "min_profit": "8.1959",
            "max_profit": "8.1959",
            "leverage": "6",
            "mark_price": "",
            "bot_close_code": "BOT_CLOSE_CODE_FAILED_INITIATION",
            "futures_pos_side": "FUTURES_POSITION_SIDE_UNSPECIFIED",
            "follow_num": 0,
            "entry_price": "370000",
            "stop_loss_price": "200000",
            "take_profit_price": "",
            "tp_sl_type": "TP_SL_TYPE_TP_PERCENT_SL_PRICE",
            "real_close_price": "",
            "min_price_precision": "0.01",
            "tick_size": "0.10",
            "used_reward_amount": "",
            "settlement_assets": "950 USDT",
            "account_type": "BOT_ACCOUNT_TYPE_FUND",
            "cum_withdrew_amount": "0",
            "current_profit": "",
            "current_per": "",
            "copy_trade_is_master": false,
            "copy_trade_follower_num": "0",
            "init_bonus": "0",
            "used_bonus_amount": "",
            "used_reward_id": "",
            "taker_fee_rate": "0.00028",
            "maker_fee_rate": "0.0001",
            "equity": "0",
            "trailing_stop_exit_equity": "0",
            "trailing_stop_per": "0.18",
            "i_m_rate": "",
            "m_m_rate": "",
            "move_up_price": "",
            "move_down_price": "",
            "curr_min_price": "",
            "curr_max_price": "",
            "adl_rank_indicator": 0
        },
        "debug_msg": ""
    },
    "retExtInfo": {},
    "time": 1774508203378
}