API Documentation

Cattle auction market data from regional US sale barns. Normalized, queryable, updated weekly.

https://hundredweight-api.kate-8ce.workers.dev

Authentication

The API uses API keys for authentication. Include your key in the Authorization header:

Authorization: Bearer hw_your_api_key_here

API keys are available on Pro and Enterprise tiers. Free and Starter users access data through the website.

The /v1/stats endpoint is public and requires no authentication.

Getting an API Key

Sign up at hundredweight.app
Upgrade to Pro ($50/mo)
Generate an API key in your account dashboard

Endpoints

GET /v1/stats

Summary statistics. Public, no authentication required.

{
  "total_auctions": 39,
  "total_states": 18,
  "total_results": 5992,
  "latest_sale_date": "2026-03-28",
  "latest_update": "2026-03-30T14:55:48.570Z"
}

GET /v1/results

Query normalized auction results with filters.

Parameter	Type	Description
`state`	string	Two-letter state code (e.g. TX, MT)
`normalized_class`	string	Canonical class (e.g. feeder_steers, slaughter_cows_boner)
`species`	string	cattle, goat, sheep, hog
`quality_grade`	string	LM1, LM2, LM3
`breed`	string	holstein, jersey, black, boer, nubian, dorper, etc.
`sex`	string	male, female, mixed, unknown
`auction_id`	string	Filter by specific auction
`weight_min`	integer	Minimum weight in lbs
`weight_max`	integer	Maximum weight in lbs
`date_from`	string	Start date (YYYY-MM-DD)
`date_to`	string	End date (YYYY-MM-DD)
`limit`	integer	Results per page (default 100, max 500)
`offset`	integer	Pagination offset

GET /v1/auctions

List all active auctions.

Parameter	Type	Description
`state`	string	Filter by state

GET /v1/auctions/:id

Get details for a single auction.

GET /v1/auctions/:id/results

Historical results for a specific auction. Supports same filters as /v1/results.

GET /v1/classes

List all canonical normalized class categories with descriptions.

{
  "classes": [
    { "id": "feeder_steers", "species": "cattle", "description": "Steers for feeding, sold CWT" },
    { "id": "slaughter_cows_boner", "species": "cattle", "description": "Slaughter cows, boner 80-85% lean" },
    ...
  ]
}

Pricing

All tiers include commercial use. No hidden fees.

Free

Calf

Website access only
Pick 2 auctions
History from signup
Same-day data

Starter

Yearling

$15/mo

Website access only
Pick 10 auctions
1 month history
Same-day data
Email support

Pro

Bull

$50/mo

Website + API access
All auctions
Full archive
10K requests/day
Same-day data
Priority support

Enterprise

Herd Boss

Custom

Website + API access
All auctions
Full archive
Unlimited requests
Bulk export
Redistribution rights
SLA + direct support

Enterprise pricing is custom. Contact us to discuss.

Examples

curl

# Get feeder steer prices in Texas
curl -H "Authorization: Bearer hw_your_key" \
  "https://hundredweight-api.kate-8ce.workers.dev/v1/results?state=TX&normalized_class=feeder_steers"

Python

import requests

response = requests.get(
    "https://hundredweight-api.kate-8ce.workers.dev/v1/results",
    headers={"Authorization": "Bearer hw_your_key"},
    params={
        "state": "TX",
        "normalized_class": "feeder_steers",
        "weight_min": 400,
        "weight_max": 600,
    }
)
data = response.json()
for r in data["results"]:
    print(f"{r['sale_date']} {r['auction_name']}: ${r['price_cwt_avg']}/cwt")

JavaScript

const res = await fetch(
  "https://hundredweight-api.kate-8ce.workers.dev/v1/results?species=cattle&limit=10",
  { headers: { "Authorization": `Bearer ${apiKey}` } }
);
const { results } = await res.json();
results.forEach(r =>
  console.log(`${r.sale_date} ${r.normalized_class} $${r.price_cwt_avg}/cwt`)
);

Response Format

{
  "total": 44,
  "limit": 100,
  "offset": 0,
  "tier": "pro",
  "results": [
    {
      "auction_id": "31",
      "sale_date": "2026-03-28",
      "animal_class": "Steers 400-500 lbs",
      "normalized_class": "feeder_steers",
      "species": "cattle",
      "normalized_weight_min": 400,
      "normalized_weight_max": 500,
      "quality_grade": null,
      "breed": null,
      "price_cwt_low": 390,
      "price_cwt_high": 600,
      "price_cwt_avg": 495,
      "head_count": null,
      "auction_name": "Cattlemen's Livestock",
      "city": "Paris",
      "state": "TX"
    }
  ]
}

Error Codes

Status	Meaning
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — API key deactivated or auction not in your selection
`404`	Not found — endpoint or resource doesn't exist
`429`	Rate limit exceeded — upgrade your tier or wait until tomorrow
`500`	Server error — try again or contact support

All errors return JSON: {"error": "Description of the problem"}