# USDA Livestock Price Anomaly Alerts (`kevinserver24/usda-livestock-price-anomaly-alerts`) Actor

Watches USDA AMS livestock-auction markets (sale barns) for a sharp week-over-week price move in one commodity/class/weight-break/price-unit combination, and flags it as an alert once it crosses a threshold you set. Charged per real alert delivered, never per check.

- **URL**: https://apify.com/kevinserver24/usda-livestock-price-anomaly-alerts.md
- **Developed by:** [Kevin](https://apify.com/kevinserver24) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$32.00 / 1,000 price anomaly alert delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## USDA Livestock Price Anomaly Alerts — did this market's price just move?

*An independent tool. It is not affiliated with, endorsed by, or operated by
USDA or the Agricultural Marketing Service. USDA Market News reports are US
government works (17 U.S.C. §105) and AMS's own privacy statement describes
information on its site as "considered public information and may be
distributed or copied." This Actor reads AMS's MARS API and reports what it
returns, reshaped into a period-over-period alert.*

**No scraper.** This Actor never touches a USDA web page's HTML. Its data
comes from AMS's MARS API (`marsapi.ams.usda.gov`), refreshed on a schedule
and bundled into this Actor at build time.

***

### Why this exists

Checking whether this week's price at a sale barn moved sharply from last
time means reading that market's own report history yourself, market by
market, and doing the arithmetic by hand. This Actor does that arithmetic
for you and only tells you when it crosses a threshold you set — a real
alert, not a raw feed you still have to watch.

v1 covers **6 livestock-auction markets** — Unionville Livestock Market
(MO), Oklahoma National Stockyards (OK), Huss Livestock (NE), Frisco City
Stockyards (AL), Athens Regional Stockyard (TN), and Lexington Livestock
Auction (KY) — for **Feeder Cattle, Steers or Heifers, Per Cwt**, across the
common 400-900 lb weight breaks — the same markets and slice the sibling
comparison product (`usda-livestock-price-comparison`) already found report
densely and consistently enough to support this kind of analysis.

### What you give it

- `market_report_slugs` — which of the 6 covered markets to watch (their
  AMS report slug ids).
- `commodity`, `animal_class`, `weight_break_low`, `weight_break_high`,
  `price_unit` — the ONE group to watch (v1: Feeder Cattle, Steers/Heifers,
  common weight breaks, Per Cwt).
- `anomaly_threshold_pct` — how large a move (in percent) counts as an
  alert. Default 10, set from this product's own measurement on real
  2025-2026 data (median week-over-week move 5.0%, about 17% of periods
  moved 10% or more).

### What comes back

One row per requested market: its most recent period-over-period price
change for the requested group (the two report dates compared, the two
average prices, the percent change, the direction), whether it crossed your
threshold (`is_anomaly`), and how many report dates were available to judge
it from. A market with too little recent history, or a quiet period, still
gets a row — `charged: false` with a plain-English `not_charged_reason` —
never a silent gap.

### Billing

Charged **only for a real alert** — a period-over-period move that actually
crossed your threshold (`price-anomaly-alert-delivered`). A quiet period or
a market with fewer than two comparable recent reports is delivered free,
with a reason. You pay for signal, not for every check.

### Data freshness

The alert is only as current as the last scheduled refresh. Each market's
own most recent report dates for the requested group are kept; the
period-over-period comparison always uses the two most recent of those.

### A note on scope

Only "Per Cwt" (per-hundredweight) prices are compared. AMS reports the
same commodity/class/weight combination under other price units too ("Per
Head", "Per Unit", "Per Family") — mixing them produces nonsense swings
(this Actor's own development found +895%/+797% fake moves this way before
the fix). Every group this Actor compares is pinned to one price unit at a
time, by construction.

# Actor input Schema

## `market_report_slugs` (type: `array`):

One USDA AMS MARS API livestock-auction report slug id per line -- each one a sale barn/stockyard. v1 covers 6 markets: 1237 (Unionville Livestock Market, MO), 1280 (Oklahoma National Stockyards, OK), 1848 (Huss Livestock, NE), 1984 (Frisco City Stockyards, AL), 2060 (Athens Regional Stockyard, TN), 2127 (Lexington Livestock Auction, KY). A market outside this list returns a free, non-billable row explaining why, not an error. Up to 25 markets per run.

## `commodity` (type: `string`):

v1 covers exactly one commodity: "Feeder Cattle".

## `animal_class` (type: `string`):

v1 covers "Steers" or "Heifers".

## `weight_break_low` (type: `integer`):

The lower bound of the weight break to watch, e.g. 600. v1 covers the common 400-900 lb breaks in 50 lb increments.

## `weight_break_high` (type: `integer`):

The upper bound of the weight break to watch, e.g. 650.

## `price_unit` (type: `string`):

v1 covers "Per Cwt" (per hundredweight) only.

## `anomaly_threshold_pct` (type: `integer`):

How large a period-over-period price move must be, in percent, before it is flagged (and charged for) as an alert. Set from this product's own kill test on real 2025-2026 data: the median week-over-week move was 5.0%, and about 17% of periods moved 10% or more. Default 10 flags roughly one period in six at that measured rate. Anything from 1 to 100 is accepted; an out-of-range or missing value falls back to 10.

## Actor input object example

```json
{
  "market_report_slugs": [
    "1237",
    "1280",
    "1848",
    "1984",
    "2060",
    "2127"
  ],
  "commodity": "Feeder Cattle",
  "animal_class": "Steers",
  "weight_break_low": 600,
  "weight_break_high": 650,
  "price_unit": "Per Cwt",
  "anomaly_threshold_pct": 10
}
```

# Actor output Schema

## `results` (type: `string`):

One row per requested market -- the most recent period-over-period price change for the requested group, and whether it crossed your anomaly threshold.

## `resultsCsv` (type: `string`):

The same rows as a spreadsheet.

## `summary` (type: `string`):

How many markets were watched, how many alerts were charged and how many were free, and when the underlying cache was last refreshed.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "market_report_slugs": [
        "1237",
        "1280",
        "1848",
        "1984",
        "2060",
        "2127"
    ],
    "commodity": "Feeder Cattle",
    "animal_class": "Steers",
    "weight_break_low": 600,
    "weight_break_high": 650,
    "price_unit": "Per Cwt",
    "anomaly_threshold_pct": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("kevinserver24/usda-livestock-price-anomaly-alerts").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "market_report_slugs": [
        "1237",
        "1280",
        "1848",
        "1984",
        "2060",
        "2127",
    ],
    "commodity": "Feeder Cattle",
    "animal_class": "Steers",
    "weight_break_low": 600,
    "weight_break_high": 650,
    "price_unit": "Per Cwt",
    "anomaly_threshold_pct": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("kevinserver24/usda-livestock-price-anomaly-alerts").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "market_report_slugs": [
    "1237",
    "1280",
    "1848",
    "1984",
    "2060",
    "2127"
  ],
  "commodity": "Feeder Cattle",
  "animal_class": "Steers",
  "weight_break_low": 600,
  "weight_break_high": 650,
  "price_unit": "Per Cwt",
  "anomaly_threshold_pct": 10
}' |
apify call kevinserver24/usda-livestock-price-anomaly-alerts --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kevinserver24/usda-livestock-price-anomaly-alerts"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/GvkNlGcUiJ4EdRmEr/builds/5wnTsysuHRbAvg5fE/openapi.json