GET /v3/item/:id/bids — bid history

GET

/v3/item/{itemId}/bids

const url = 'https://api-ha-prod-p8.handbid.dev/v3/item/example/bids?limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api-ha-prod-p8.handbid.dev/v3/item/example/bids?limit=20' \
  --header 'Authorization: Bearer <token>'

NEW (HAN-1690). Paginated bid history for an item. iOS lazy-loads this when the user opens the bid-history tab; the main item-detail response stays lean.

Auth: OPTIONAL Bearer. With a token, isCurrentUser flips per row; anonymous → always false.

Query: limit (1-100, default 20), offset (default 0). Ordered newest-first (bids.id DESC).

Response:

{
  "bids": [
    { "id": 12700256, "paddleNumber": 173, "bidderName": "Paddle#173",
      "amount": 130.0, "status": "winning", "time": 1781518101, "isCurrentUser": true }
  ],
  "totalCount": 4
}

amount is a float in the auction’s currency. time is bids.dateInserted (epoch). bidderName follows the same showName→alias→Paddle# rule as the item-detail winning-bidder label.

⚠️ totalCount and the list are HISTORY-INCLUSIVE. Both filter status IN ('winning','losing','purchase','removed','replaced') — so totalCount is the number of visible-history bid rows, NOT the number of active bids or distinct bidders:

A single proxy / max-bid escalation writes two rows — the original bid flips to replaced (statusReason='added_maxbid') and the new max_bid row becomes winning — so one bidder’s proxy can add 2+ to totalCount.
A withdrawn bid stays as a removed row and is still counted.
An item a human reads as “1-2 bids” can legitimately report totalCount: 3+. This is expected, not a miscount. Excluded statuses: failed, incomplete, sold_out, winning_changed, transferred.

Paddle (HAN-2113): paddleNumber is one deterministic paddle per bid (the bidder’s lowest active auction_user_relation.paddleId). A bidder can hold more than one active paddle in an auction (linked/merged records); the endpoint collapses that to a single stable value so a bid is never duplicated in the list.

Errors: 400 when :id ≤ 0; 404 not_found (same privacy gate as item detail).

Cache: per-user key, 10s TTL, tag V3CacheTags::auction($auctionId) (invalidated on AR-mediated bid writes via HbBid::afterSave/afterDelete).

Authorizations

bearer

Parameters

Path Parameters

itemId

required

string

Query Parameters

limit

integer

1-100, default 20

Example

Responses

200

Successful response

application/json