AllSurplus APIallsurplus.com ↗
Access AllSurplus B2B surplus auction data: search lots, fetch asset details, browse auction events, and retrieve category/location hierarchies via 6 endpoints.
What is the AllSurplus API?
The AllSurplus API exposes 6 endpoints covering industrial surplus and B2B auction data from allsurplus.com. Use search_assets to query live auction lots by keyword, category, seller, or closing time, then call get_asset_detail to retrieve full lot information including photos, long HTML description, location coordinates, seller info, and payment instructions. Two additional endpoints cover auction events, and two return the full category and location hierarchies.
curl -X POST 'https://api.parse.bot/scraper/f6ee20f8-b2d1-4a4d-be82-cae28e1ded7c/search_assets' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"page": "1",
"limit": "5",
"query": "truck",
"sort_field": "bestfit",
"sort_order": "asc"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace allsurplus-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""AllSurplus SDK — search surplus assets, browse auction events, explore categories."""
from parse_apis.allsurplus_api import AllSurplus, SortField, Sort, ResourceNotFound
client = AllSurplus()
# Search for auction assets sorted by close date, capped at 3 results.
for asset in client.assetsummaries.search(query="forklift", sort_field=SortField.CLOSE_DATE, sort_order=Sort.ASC, limit=3):
print(asset.assetShortDescription, asset.currentBid, asset.locationState)
# Drill into the first result's full detail (photos, instructions, attributes).
summary = client.assetsummaries.search(query="truck", limit=1).first()
if summary:
detail = summary.details()
print(detail.assetShortDesc, detail.makebrand, detail.city, detail.state)
for group in detail.assetAttributeGroups:
for attr in group.assetAttributes:
print(f" {attr.label}: {attr.value}")
# Browse upcoming auction events and fetch one event's full info.
event_summary = client.auctioneventsummaries.list(limit=1).first()
if event_summary:
try:
event = event_summary.details()
print(event.saleEventTitle, event.timeRemaining)
except ResourceNotFound as exc:
print(f"Event gone: {exc}")
# Retrieve the category hierarchy for filtering future searches.
categories = client.categorymenus.get()
for cat in categories.menus:
print(cat.menuDescription, cat.count)
print("exercised: assetsummaries.search / details / auctioneventsummaries.list / details / categorymenus.get")
Search and browse auction lots with keyword, category, seller, event, and time-based filters. Returns paginated asset summaries with bid info and facets for further narrowing. Each result carries the assetId and accountId needed to fetch its full detail via get_asset_detail. Sorted by relevance by default; closedatetime and currentbid are alternatives.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| limit | integer | Number of results per page. |
| query | string | Search keyword. Use '*' for all results. |
| event_id | string | Event ID to filter results by a specific auction event. |
| time_type | string | Time-based filter such as 'closingToday' or 'newListings'. |
| sort_field | string | Field to sort results by. |
| sort_order | string | Sort direction. |
| account_ids | string | Comma-separated list of numeric account IDs to filter by seller. |
| category_ids | string | Category ID to filter results (from list_categories endpoint). |
| facets_filter | string | JSON array of facet filter strings (e.g. '["region:\"Americas\""]'). |
{
"type": "object",
"fields": {
"total": "integer total number of matching assets",
"assets": "array of asset summary objects with assetId, accountId, assetShortDescription, makebrand, model, modelYear, currentBid, locationCity, locationState, country, assetAuctionEndDate, categoryDescription, companyName, currencyCode, timeRemaining, photo",
"facets": "array of facet objects for further filtering"
}
}About the AllSurplus API
Searching and Retrieving Auction Lots
The search_assets endpoint accepts keyword queries (use '*' for all results), account_ids for filtering by specific sellers, event_id to scope results to one auction, and time_type values like closingToday or newListings. Results are paginated via page and limit, sortable by a sort_field and sort_order, and include facet arrays for progressive narrowing. Each result in the assets array carries assetId, accountId, assetShortDescription, makebrand, model, modelYear, currentBid, and locationCi. The assetId and accountId pair is required to call get_asset_detail.
Full Lot Details
get_asset_detail returns the complete record for one lot: assetLongDesc (HTML), assetPhotos (array of URL paths), makebrand, model, modelYear, city/state/country location fields, and seller accountId. This is the endpoint to use when building a lot display page, populating inspection or removal instructions, or indexing equipment specifications.
Auction Events
list_auction_events returns paginated event summaries sorted by close date ascending. Each record includes saleEventId, saleEventTitle, saleEventDescription, openDatetime, closeDatetime, and openAssetCount. Passing a facets_filter JSON array lets you narrow the event list. get_auction_event_detail takes a saleEventId and returns the full event record: HTML saleEventDescription, importantNotice, contactDetails, timeRemaining, and formatted display datetimes.
Category and Location Hierarchies
list_categories returns the complete three-level category tree (L0 > L1 > L2). Each node has a menuId, menuDescription, asset count, and nested children. The menuId values feed directly into search_assets for category-scoped queries. list_locations returns the same tree shape but structured as Region > Country > State, with menuId values usable as facet filters in search_assets. Neither endpoint requires input parameters.
The AllSurplus API is a managed, monitored endpoint for allsurplus.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when allsurplus.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official allsurplus.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor lots closing today by passing
time_type: 'closingToday'to search_assets and tracking currentBid changes. - Build an equipment index by iterating list_categories and running category-scoped search_assets queries for each menuId.
- Aggregate seller inventory by filtering search_assets with account_ids to list all lots from a specific auction house.
- Display auction event schedules by calling list_auction_events and surfacing openDatetime, closeDatetime, and openAssetCount.
- Populate a lot detail page using assetPhotos, assetLongDesc, and location fields from get_asset_detail.
- Filter available lots by geography using location menuIds from list_locations as facets in search_assets.
- Alert users to new listings in specific categories by polling search_assets with time_type 'newListings' and a target menuId.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does AllSurplus have an official developer API?+
What does get_asset_detail return that search_assets does not?+
Can I retrieve bid history or individual bidder data for a lot?+
How does pagination work across search_assets and list_auction_events?+
page and limit parameters. search_assets also returns a total integer so you can calculate the number of pages. list_auction_events similarly returns a total field alongside the events array.