---
title: "List auctions with pagination and filtering"
method: GET
path: "/api/v1/auctions"
tags: ["Auctions"]
---

# List auctions with pagination and filtering

`GET /api/v1/auctions`

Retrieve a paginated list of auctions with advanced filtering options. Requires authentication with read permissions.

## Query parameters

- `limit` integer — Number of items per page
- `cursor` string — Cursor for pagination
- `state` 'scheduled' | 'active' | 'settling' | 'settled' — Filter by auction state
- `created_by` string — Filter by creator user ID
- `include_metadata` boolean, nullable — Include auction metadata
- `include_revenue` boolean, nullable — Include revenue information
- `from_date` number, nullable — Start date as Unix timestamp
- `to_date` number, nullable — End date as Unix timestamp
- `slot_from` integer, nullable — Starting slot number
- `slot_to` integer, nullable — Ending slot number
- `sort_by` 'createdAt' | 'slot' | 'state' | 'endTime' | 'settledAt' | 'totalBids'
- `sort_order` 'asc' | 'desc' — Sort order

## Response `200`

Successful operation with enhanced pagination

- object
  - `success` true, required
  - `timestamp` number, required
  - `data` object[], required
    - `id` string, required — Unique auction identifier
    - `slot` integer, required — Ethereum slot number
    - `state` 'scheduled' | 'active' | 'settling' | 'settled', required
    - `createdAt` number, required — Creation timestamp
    - `scheduledStart` number, required — Scheduled start timestamp
    - `actualStart` number — Actual start timestamp
    - `endTime` number, required — End timestamp
    - `settledAt` number — Settlement timestamp
    - `minBid` string, required — Minimum bid amount in wei
    - `elasticSupply` object, required
      - `basePrice` string, required — Base price in wei
      - `maxCapacity` integer, required — Maximum capacity
      - `minCapacity` integer, required — Minimum capacity
      - `elasticity` number, required — Elasticity factor (0-1)
    - `currentSupply` integer, required — Current allocated supply
    - `totalBids` integer, required — Total number of bids
    - `clearingPrice` string — Clearing price in wei
    - `highestBidAmount` string — Highest bid amount in wei (no bidder info)
    - `createdBy` string, required — ID of user who created the auction
    - `metadata` object — Additional auction metadata
    - `biddingRounds` integer, required — Number of bidding rounds
    - `lastBidAt` number — Timestamp of last bid
    - `settledBy` string — ID of user who settled the auction
    - `settlementReason` string — Reason for settlement
    - `gasUsed` string — Gas used for settlement
    - `revenueDistribution` object
      - `totalRevenue` string, required — Total revenue generated
      - `platformFee` string, required — Platform fee amount
      - `netRevenue` string, required — Net revenue after fees
  - `cursor` string
  - `hasMore` boolean, required
  - `total` number
  - `count` number, required
  - `metadata` object, required
    - `totalPages` number
    - `currentPage` number
    - `pageSize` number, required
    - `firstItemTimestamp` number
    - `lastItemTimestamp` number

## Other responses

- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Insufficient permissions
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error

---

[API](https://skmtc.net/manifoldfinance/apis/xga-auction-system-api.md) · [All operations](https://skmtc.net/manifoldfinance/apis/xga-auction-system-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/manifoldfinance/xga-auction-system-api/versions/329190dccb50/schema)