FreightAPIs API · Developer Reference

Shipment Tracking

Track a shipment by carrier and reference number — PRO, BOL, PO or load ID — and get its status and history in one shape for every carrier. Starter plan and up.

Get API Key Download OpenAPI spec Track on the website

GET /api/track/carriers

List Tracking Carriers

Every carrier with a tracking page, whether it is open to the API (available), the reference types it accepts (refTypes, passed as type) and the number format (refPattern). Not billed, and open to every plan. Open to the API today: abf (ABF Freight), aaa-cooper (AAA Cooper), ait (AIT Worldwide), ceva (CEVA Logistics), chrobinson (C.H. Robinson), customco (The Custom Companies), daylight (Daylight Transport), echo (Echo Global Logistics), flockfreight (Flock Freight), forward (Forward Air), ldt (Line Drive Trucking), mothership (Mothership), numark (Numark Transportation), pilot (Pilot Freight Services), rl-carriers (R+L Carriers), roadrunner (Roadrunner Freight), saia (Saia), sefl (Southeastern Freight Lines), tforce (TForce Freight), total-transportation (Total Transportation), tql (TQL), uber-freight (Uber Freight), warp (WARP Freight). The other carriers can be tracked for free on their tracking pages.

Code Examples

curl "https://freightapis.dev/api/track/carriers" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "carriers": [
    {
      "carrier": "uber-freight",
      "name": "Uber Freight",
      "available": true,
      "refTypes": [
        {
          "type": "load",
          "label": "Load ID"
        },
        {
          "type": "bol",
          "label": "BOL number"
        }
      ],
      "defaultType": "load",
      "refPattern": "^[A-Za-z0-9-]{3,40}$",
      "page": "https://freightapis.dev/track/uber-freight"
    }
  ],
  "limits": {
    "perCarrierPerDay": 2000,
    "whenMostlyNotFoundPerDay": 100,
    "batchMax": 25
  }
}

GET /api/track/:carrier?ref=:number&type=:type

Track a Shipment

The current status and history of one shipment, straight from the carrier, in one shape for every carrier. status is always one of pending, picked_up, in_transit, out_for_delivery, delivered, exception, cancelled or unknown; statusText keeps the carrier's own wording. Events are newest first. A number can match several shipments (a BOL or PO), so shipments is a list. Starter plan and up.

Answers are cached for about 10 minutes while in transit, 24 hours once delivered and 5 minutes when not found; cached: true says so. Polling faster than that returns the same answer. A number the carrier does not know returns 404 with reason: "not_found"; a carrier that cannot be reached returns 503.

Code Examples

curl "https://freightapis.dev/api/track/tql?ref=38996062" \
  -H "X-API-Key: YOUR_API_KEY"

const FreightAPIs = require('freightapis');
const fa = new FreightAPIs(process.env.FREIGHTAPIS_KEY);
const r = await fa.track('uber-freight', '123456789', { type: 'load' });
console.log(r.shipments[0].status);

from freightapis import FreightAPIs
fa = FreightAPIs(os.environ["FREIGHTAPIS_KEY"])
r = fa.track("uber-freight", "123456789", type="load")
print(r["shipments"][0]["status"])

{
  "carrier": "tql",
  "ref": "38996062",
  "refType": null,
  "cached": false,
  "shipments": [
    {
      "id": "38996062",
      "status": "in_transit",
      "statusText": "In Transit",
      "origin": {
        "city": "Lafayette",
        "state": "IN"
      },
      "destination": {
        "city": "Puyallup",
        "state": "WA"
      },
      "pickedUp": null,
      "estimatedDelivery": null,
      "delivered": null,
      "appointment": null,
      "pieces": null,
      "weightLbs": null,
      "events": [
        {
          "date": "2026-10-29",
          "time": "14:05",
          "timezone": "UTC-5",
          "status": "In Transit",
          "description": null,
          "code": null,
          "location": "Billings, MT"
        }
      ],
      "details": {
        "nextStop": "Puyallup, WA"
      }
    }
  ]
}

POST /api/track/batch

Batch Tracking

Up to 25 lookups in one request, across any carriers, run in parallel. Each result carries the status it would have had on its own. Billed one call per item; charged says how many calls were kept after refunds. If your remaining allowance and top-up balance cannot cover every item, nothing runs and nothing is charged (429). Starter plan and up.

Code Examples

curl -X POST "https://freightapis.dev/api/track/batch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"carrier": "tql", "ref": "38996062"}, {"carrier": "mothership", "ref": "MS5016101"}]}'

{
  "charged": 1,
  "results": [
    {
      "status": 200,
      "carrier": "tql",
      "ref": "38996062",
      "refType": null,
      "cached": true,
      "shipments": [
        "…"
      ]
    },
    {
      "status": 503,
      "carrier": "mothership",
      "ref": "MS5016101",
      "refType": null,
      "error": "Mothership tracking is not responding. Try again in a few minutes.",
      "reason": "upstream"
    }
  ]
}

Billing and Limits

Charged: one call when the lookup reached the carrier or our cache — 200, and 404 not found.
Refunded: everything else — a malformed number or type (400), a carrier not open to the API (403), a daily limit (429), the carrier being down (503). Calls paid from your top-up balance go back to it.
Daily limits (UTC): 2,000 lookups per carrier. When most of a day's distinct numbers are not found, lookups are limited to 100 for the rest of the day. Over a limit you get 429 with Retry-After set to the next 00:00 UTC.
Per minute: the same 120 calls per minute as every other endpoint; a batch counts once.

Shipment Tracking - FAQ

Which carriers can I track through the API?

GET /api/track/carriers lists them with available: true. The API opens carriers one at a time as each carrier's terms are confirmed; every other carrier can still be tracked for free on its page under /track.

Which plan do I need?

Starter or higher. The carrier list is open to every plan, so you can check coverage before upgrading. Free tracking for people, one number at a time, is on the website.

Am I charged when a number is not found?

Yes: the carrier was asked and answered. You are not charged when the carrier cannot be reached, when the number is malformed, or when a limit stops the lookup; those calls are refunded.

How often can I poll a shipment?

Answers are cached for about 10 minutes while a shipment moves and 24 hours once it is delivered. Polling more often returns the same cached answer and still counts as a call, so every 15 to 30 minutes is plenty.

Does the API show shipper or consignee details?

No. It returns the same allow-listed fields as the public tracking page: status, places at city level, dates, pieces, weight and events. Names, street addresses, phone numbers, charges and signer names are dropped.