You run logistics for a coal shipper, and this week you have a job that sounds simple: wire your dispatch system to the BNSF Trains API so it can pull tracing details for your unit trains. You open the contract, generate a client, and start sketching how you will batch your fleet into as few calls as possible.
The API gives you the current status and tracing details for unit trains on one of North America's largest freight networks. It has four operations. One is a GET on /v1/trains that returns status and tracing for all unit train types. The other three are POST calls: /v1/ag-trains, /v1/coal-trains and /v1/ip-trains. The responses are detailed. You get loaded and empty car counts, the last event description and time, the last reported latitude and longitude, origin and destination stations, and estimated shipment availability. For agricultural shuttles you also get the owner, requester and trip operator abbreviations. Even the train ID schema explains its own grammar, from the symbol through the departure day to a schedule letter from A to Z.
Then you hit the part that stops you. The summary on each of those three POST operations says it returns tracing details for up to 25 trains. But the request schema tells a different story. The arrays you send, train_list_ag, train_list_coal and train_list_ip, each declare minItems of 1 and maxItems of 300. So the client you just generated will happily send 300 train IDs, while the summary you read tells you to stop at 25.
The contract does document a 413 Payload Too Large on each of these calls. That means the gateway has a real limit somewhere between 25 and 300. The document does not say where.
That gap matters because of the rate limit, which is the real design constraint here. 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 means your throughput depends partly on everyone else calling the same service. With 15 calls a minute, batching is not optional, so you need a straight answer on batch size and the contract does not give you one.
There is a second surprise in how you get access. The base URL is https://api.bnsf.com:6443. The 403 description says 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. It points you to the Mutual Authentication section of BNSF's Getting Started documentation. So this is mutual TLS. Yet the contract itself declares no security scheme.
Here is where the post turns on its own record. APIs.io's agent readiness record for BNSF lists auth_clarity as bearer, which is not what the error text describes. The post says plainly that this one is theirs to check. So the catalog is not only pointing at a gap in BNSF's contract. It is flagging a line in its own data that does not match the evidence.
For context, the post reports that BNSF scores 49.2, rated developing, on the Kin Score as of 2026-11-02, up 1.6 from 47.6. It scores 29.4 on Agent Readiness. Discoverability is its strongest facet at 78.6, and 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 the post calls rarer than it should be in rail.
What you take away is practical. Plan your batching around 25 trains until BNSF confirms otherwise, even though the schema would let you send 300. Budget 15 calls a minute, and remember the shared 100-per-minute ceiling across all partners. Get your client certificate in place before you write any code, because setup can take up to five business days. And do not rely on the contract alone for how authentication works, or on the catalog's own bearer label, which it has said it needs to check.
Read the original: https://apis.io/2026/11/14/bnsf-trains-api-says-up-to-25-trains-and-its-schema-accepts-300/