API Sandbox

No sign-up to tryGet a free key Contact support

Explore the API live below. Sandbox runs on a shared demo key — no sign-up, bounded to corn and the last 30 days. Liveuses your own key at your real tier (free: corn, wheat & soybean, 500 requests/day — grab one). Every endpoint authenticates with Authorization: Bearer — copy the curl to call it from your code.

Try it · Sandbox

Shared demo key, no sign-up. Bounded to corn, the last 30 days, one series per source.

Endpoint

commodity

Pinned in sandbox

source

start_date

Pinned in sandbox

end_date

Pinned in sandbox

limit

as_of

format

Series Data

Historical grain price observations

GET/v1/series key required

Price series

Returns historical grain price observations from USDA AMS, FRED, and NASS. Requires an API key (`Authorization: Bearer <key>`), like every /v1 endpoint. The free tier covers corn, wheat, and soybean at 500 requests/day (keys created before 2026-08-20 keep 2,000 — check `grandfathered` on `/v1/me`).

Parameters

commodityquery · requiredcorn | soybean | wheat
sourcequeryAMS | FRED | NASSFilter by data source. Omit to return all sources.
start_datequery
end_datequery
limitquery
as_ofqueryVintage cutoff. Returns the data as it was known on this date, using the per-row ingestion timestamp.
formatqueryjson | csv`csv` returns the rows only, so the body loads directly into pandas/R/Excel. Pagination, freshness, warning severity and attribution move to `X-DataCrop-*` response headers.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/series?commodity=corn&start_date=2024-01-01&end_date=2025-06-01&as_of=2026-01-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/commodities key required

List commodities

Returns all commodities and their free-tier availability.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/commodities" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/freshness/{commodity} key required

Data freshness

Returns the last ingested date and row count per source for a commodity.

Parameters

commoditypath · requiredcorn | soybean | wheat

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/freshness/corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/identifiers key required

Identifiers behind a commodity

Every source_ref DataCrop serves for a commodity — FRED series ids, AMS report slug_ids, NASS descriptors — with the curated primary marked. This is the lookup behind `source_ref` on /v1/series, /v1/basis and /v1/revisions. Available on all tiers, scoped to the commodities your tier grants.

Parameters

commodityquery · required
sourcequeryAMS | FRED | NASSFilter by source. Omit for all.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/identifiers?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/catalog key required

Series catalog

The FRED series and AMS slugs DataCrop tracks, with their caveats and relations, read from the catalog files the pipeline itself runs on. No API key required.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/catalog" \
  -H "Authorization: Bearer YOUR_API_KEY"

Forecasts

LightGBM price forecast bands, published up to 3 weeks ahead

GET/v1/forecasts key required

Price forecast band (up to 3 weeks)

Returns the latest LightGBM forecast band (P10/P50/P90), published up to 3 weeks ahead for a grain commodity (corn, soybean, or wheat — the series with live USDA AMS cash bids). Commodities without an AMS bid feed have price data but no forecast. Requires an API key on a Pro or higher tier — free-tier keys receive 403 `forecasts_not_included`.

Parameters

commodityquery · requiredcorn | soybean | wheat

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/forecasts?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/forecasts/history key required

Past forecast runs

Previous forecast runs for a commodity, newest first, so a published band can be compared against what actually happened. Pro+ tier required (403 forecasts_not_included).

Parameters

commodityquery · required
limitqueryNumber of forecast runs to return.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/forecasts/history?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/forecasts/drivers key required

What moved the latest run

Per-feature SHAP contributions for the latest forecast run, with a plain-English narrative. Explains the model that produced the band; it is not a causal claim about the market. Max+ tier required (403 drivers_not_included).

Parameters

commodityquery · required

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/forecasts/drivers?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Alerts

Price alert rule management

GET/v1/alerts key required

List alert rules

Returns all active alert rules for the authenticated API key. Max+ tier required.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/alerts key required

Create alert rule

Creates a new price alert rule. Max+ tier required.

Body (JSON)

commoditystring · required
sourcestringAMS | FRED | NASS
threshold_typestring · requiredabove | below
threshold_valuenumber · required
notify_emailstring
notify_webhook_urlstring

Example request

curl -X POST \
  "https://api.datacrop.dev/v1/alerts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"commodity":"corn","threshold_type":"above","threshold_value":5}'

GET/v1/alerts/{id} key required

Get one alert rule

Returns a single alert rule owned by the authenticated key. Max+ tier required.

Parameters

idpath · requiredAlert rule UUID (from the create or list response)

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/alerts/id" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/v1/alerts/{id} key required

Delete alert rule

Soft-deletes an alert rule by ID. Returns 204 No Content on success.

Parameters

idpath · requiredAlert rule UUID (from the create or list response)

Example request

curl -X DELETE \
  "https://api.datacrop.dev/v1/alerts/id" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/alerts/{id}/events key required

Alert trigger history

Every recorded trigger for one alert rule, with the observed value against the threshold and whether a notification was sent. Max+ tier required. Note `notification_sent` currently reflects only the send paths that write it back; read it as "recorded as sent", not as proof of delivery.

Parameters

idpath · requiredAlert rule UUID (from the create or list response)
limitquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/alerts/id/events" \
  -H "Authorization: Bearer YOUR_API_KEY"

Export

Bulk data export

GET/v1/export key required

Export CSV

Generates a bulk CSV of price series and returns a signed download URL — the response body is JSON, not the CSV itself. Identical requests reuse the cached file. Team+ tier required (403 export_not_included). For a CSV body inline, use /v1/series?format=csv.

Parameters

commodityquery · required
sourcequeryAMS | FRED | NASSRepeatable.
start_datequery
end_datequery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/export?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Provenance

Restatement history, normalization receipts, redistribution terms, and the upstream release calendar

GET/v1/revisions key required

price restatement log

The log of value restatements. Captured at the moment a published price is overwritten — the only moment the previous value is still knowable — so the history runs forward from when tracking began and cannot be backfilled. The `coverage` block reports how far back this log actually reaches. Pro+ tier required.

Parameters

commodityquery · required
sourcequeryAMS | FRED | NASS
source_refquery
observed_datequery
sincequeryOnly restatements observed on or after this date.
limitquery
offsetquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/revisions?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/lineage key required

Normalization receipt

Every filter, conversion and exclusion applied between the raw USDA response and the series you query, itemised from the same catalog files the pipeline runs on. Counts are derived at request time. Available on all tiers.

Parameters

commodityquery · required

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/lineage?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/license key required

Redistribution terms

Machine-readable provenance and redistribution terms for every upstream source, each linking the statement it summarises. Available on all tiers, including free — the redistribution question gates the decision to build on a feed at all.

Parameters

sourcequeryAMS | FRED | NASSScope to specific sources. Omit for all. Repeatable.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/license" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/releases key required

Upstream release calendar

Upcoming expected report releases across DataCrop's upstream sources. Each row carries its own `confidence`: `scheduled` rows come from the publisher's posted schedule, `cadence_estimate` rows are computed from the source's typical cadence and can shift with federal holidays. Every row links a `verify_url` to the authoritative schedule. Available on all tiers.

Parameters

daysqueryLook-ahead window in days (1-90).

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/releases" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fundamentals

PSD balance sheets, FAS export sales, EIA energy, GTR freight, CFTC positioning and weather event markers

GET/v1/fundamentals key required

PSD balance sheets

USDA FAS Production, Supply and Distribution balance-sheet attributes (production, ending stocks, stocks-to-use and the rest) by market year. `attribute` requires `commodity`, because the underlying series_ref is commodity-scoped. Pro+ tier required (403 fundamentals_not_included).

Parameters

commodityquery
attributequeryBalance-sheet attribute (e.g. production, ending_stocks, stocks_to_use). Requires commodity.
market_year_startqueryFirst PSD market year (e.g. 2020 = MY 2020/21).
market_year_endqueryLast PSD market year, inclusive.
limitquery
offsetquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/fundamentals?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/exports key required

FAS export sales (ESR)

USDA FAS Export Sales Reporting weekly series: weekly exports, outstanding sales and net sales. `metric` requires `commodity`. Not to be confused with /v1/export, which returns a bulk CSV of price series. Pro+ tier required (403 fundamentals_not_included).

Parameters

commodityquerycorn | wheat | soybean
metricqueryweekly_exports | outstanding_sales | net_salesRequires commodity.
startqueryWeek ending on/after.
endqueryWeek ending on/before.
limitquery
offsetquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/exports?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/energy key required

EIA energy context

EIA energy series that sit upstream of grain costs — diesel, natural gas, ethanol. Address a series either by the friendly `series` alias or by its exact EIA `series_ref`; passing both is rejected rather than silently resolved. Pro+ tier required (403 fundamentals_not_included).

Parameters

seriesquerydiesel | natgas | ethanolFriendly alias.
series_refqueryExact EIA series id (e.g. EMD_EPD2D_PTE_NUS_DPG).
startqueryperiod_start on/after.
endqueryperiod_start on/before.
limitquery
offsetquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/energy" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/freight key required

Grain transportation rates

USDA AMS Grain Transportation Report series: barge rates, ocean rates and rail auction results, addressed by dataset, route/segment key or region. Pro+ tier required (403 fundamentals_not_included).

Parameters

datasetquerybarge_rates | ocean_rates | rail_auction
series_refquerySegment/route key, e.g. illinois_river, us_gulf_to_japan.
regionqueryExact region label (e.g. 'Illinois River'); an empty string matches national rows.
startqueryperiod_start on/after.
endqueryperiod_start on/before.
limitquery
offsetquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/freight" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/positioning key required

CFTC Commitments of Traders

CFTC COT positioning per listed futures contract: net non-commercial, net commercial and open interest. One row per (series_ref, period_start), where series_ref is '<contract code>:<metric>'. This is the published positioning report, not a futures price feed — DataCrop serves no futures prices. Pro+ tier required (403 fundamentals_not_included).

Parameters

commodityqueryCommodity slug with a listed futures contract.
series_refquery'<contract code>:<metric>', metric in net_noncomm | net_comm | open_interest.
start_datequery
end_datequery
limitquery
offsetquery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/positioning?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/weather-events key required

Drought and ENSO event markers

Derived drought (USDM) and ENSO (CPC ONI) event markers over the growing regions of each commodity, with the derivation rule stated in `method` and the real cutoff of each source in `data_through`. When no USDM/ONI rows are stored the call returns 503 rather than an empty 200, because an empty list would read as "monitored, nothing happened". Pro+ tier required (403 fundamentals_not_included).

Parameters

commodityqueryLimit drought markers to one commodity slug.
start_datequery
end_datequery

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/weather-events?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Procurement

Buy-timing signal and margin modelling

GET/v1/procurement/signal key required

Buy-timing signal

Realised volatility and a cover/wait signal computed from the commodity's own recent AMS cash prices over the lookback window, with the freshness of the underlying data reported alongside. Max+ tier required (403 procurement_not_included).

Parameters

commodityquery · required
weeksqueryLookback window in weeks.
source_refqueryAMS report slug_id to compute from (see /v1/identifiers). Defaults to the curated primary.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/procurement/signal?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/procurement/margin key required

Margin model

Models gross margin for a stated cost, volume and unit against the current market price, and returns the buy-timing signal alongside so the number is read in context. Nothing is stored. Max+ tier required (403 procurement_not_included).

Body (JSON)

commoditystring · required
cost_per_unitnumber · required
selling_pricenumber
volumenumber · required
unitstring · required
target_margin_pctnumber
source_refstring

Example request

curl -X POST \
  "https://api.datacrop.dev/v1/procurement/margin" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"commodity":"corn","cost_per_unit":4.2,"volume":10000,"unit":"bu"}'

Account

What this key is and what it may reach

GET/v1/me key required

Key, tier and quota state

What this key is: its tier, the commodities it may query, today's request count and what remains, and the feature block. `grandfathered` is true when the key predates the free-tier cutover and therefore keeps the older daily limit — check it here rather than assuming either number. Available on all tiers; this call does not consume quota.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/capabilities key required

Entitlements and commodity sets, as data

Every capability this key holds and every one it does not, each naming the endpoints it unlocks. The `commodities` block reports several distinct sets with their counts and a plain-English `meaning` for each — registered, served, forecastable, band_measured, band_unmeasured, allowed, deregistered — because a commodity can be served without a model, and can publish a band that has never been scored. Counts are reported with their slug list, never as a bare percentage. Available on all tiers.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/capabilities" \
  -H "Authorization: Bearer YOUR_API_KEY"

Basis

Regional cash spreads against a benchmark identifier

GET/v1/basis key required

Regional cash basis

Each AMS identifier's cash spread against a benchmark identifier, in the commodity's canonical unit. Legs are unit-converted before subtraction and paired to the benchmark as-of their own observation date, because report calendars do not line up. Pro+ tier required.

Parameters

commodityquery · required
benchmarkquerysource_ref to spread against. Defaults to the curated primary AMS identifier.
windowquery30 | 60 | 90 | 180 | 365

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/basis?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Correlations

Pairwise commodity price correlation on weekly log-returns

GET/v1/correlations key required

Commodity price correlations

Pearson correlation between AMS commodity price series' weekly log-returns, not price levels, over a rolling window. Differencing to returns removes a shared trend that would otherwise make two independently-moving commodities look correlated. Every pair reports `n`, the overlapping weekly-return count (pairwise-complete, so it varies per pair); pairs below the reliability floor ship `insufficient: true` with `r`, `strength`, and `direction` null rather than an unreliable coefficient — `interpretation` explains why in plain language either way. An empty AMS window is a 404, never an empty `pairs` list (which would read as "these commodities are uncorrelated", a claim with no data behind it). Pro+ tier required.

Parameters

windowquery180 | 365Rolling window in days: 180 (~6 months) or 365 (~1 year, default). Both are wide enough that a commodity pair with real overlapping AMS history can clear the reliability floor; narrower windows could not.

Example request

curl -X GET \
  "https://api.datacrop.dev/v1/correlations" \
  -H "Authorization: Bearer YOUR_API_KEY"