The BNSF Trains API gives a shipper the current status and tracing details for unit trains on one of North America’s largest freight networks. It has four operations, and three of them make a promise in their summary that their own request schema does not keep.
POST /v1/ag-trains, POST /v1/coal-trains and POST /v1/ip-trains each say they return “tracing details for up to 25” agricultural, coal or industrial trains. The trainList arrays those operations accept, train_list_ag, train_list_coal and train_list_ip, each declare minItems: 1 and maxItems: 300. A client generated from the contract will happily send 300 train IDs. A developer reading the summary will stop at 25. The contract also documents a 413 Payload Too Large on each of these calls, so somewhere between 25 and 300 the gateway has a real limit, and the document does not say where.
What the API covers
| Operation | Method | What it returns |
|---|---|---|
/v1/trains |
GET | Status and tracing for all unit train types |
/v1/ag-trains |
POST | Up to 25 agricultural trains (per summary) |
/v1/coal-trains |
POST | Up to 25 coal trains (per summary) |
/v1/ip-trains |
POST | Up to 25 industrial trains (per summary) |
The response objects are detailed: loaded and empty car counts, last event description and time, last reported latitude and longitude, origin and destination stations, estimated shipment availability, and for agricultural shuttles the owner, requester and trip operator abbreviations. The train ID schema even explains its own grammar, from the symbol through the departure day to a schedule letter from A to Z.
The rate limit is the real design constraint
Every operation documents the same 429 text. The BNSF API Gateway allows 1 request per second per partner per service, 15 requests per minute per partner per service, and 100 requests per minute per service across all partners. That last number matters: your throughput depends partly on everyone else calling the same service. With 15 calls a minute, batching is not optional, which is exactly why the 25-versus-300 question needs a straight answer.
Access is mutual TLS, and the contract does not say so
The base URL is https://api.bnsf.com:6443. The 403 description tells you that setup takes “a few days” after registration, up to five business days, and that a 403 can also mean “your certificate is not configured properly”, pointing to the Mutual Authentication section of BNSF’s Getting Started documentation. The contract itself declares no security scheme. Our agent readiness record for BNSF lists auth_clarity: bearer, which is not what the error text describes. That one is ours to check.
Where BNSF stands
BNSF scores 49.2 (developing) on the Kin Score as of 2026-11-02, up 1.6 from 47.6, and 29.4 (agent-ready) on Agent Readiness. Its strongest facet is discoverability at 78.6; contract governance is its weakest at 31.8. Five contracts back the provider, and the Trains API sits next to the Automotive, Carload and Intermodal APIs. BNSF also publishes its source specifications on its own site, trace.json among them, which is rarer than it should be in rail.
Takeaway
Plan your batching around 25 trains until BNSF confirms otherwise, budget 15 calls a minute, and get your client certificate in place before you write any code. The contract is at apis.io/apis/bnsf/bnsf-trains-api/.