# From a carrier's name to its fleet


```bash
curl "https://api.cardog.app/v2/carriers?q=bison%20transport&country=CA" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "Cardog-Version: 2026-10-26"
```

A motor carrier is a company that runs trucks across a border or a state line. Each one holds a US DOT number, and that number is on every roadside inspection and every reportable crash its units are involved in. `/v2/carriers` is that register and the walk from it to the units on the road.

## 1. Find the carrier

`GET /v2/carriers?q=…` takes one of three things and says which it read:

- a name or part of one (`bison transport`), matched against legal and trade names, best match first; `state` and `country` narrow it;
- a DOT number (`245330`), which returns that one carrier;
- a 17-character VIN, which returns the carriers that unit was observed under, most recent first.

```json
{
  "query": { "q": "bison transport", "matchedAs": "name", "state": null, "country": "CA" },
  "carriers": { "count": 1, "items": [
    { "dotNumber": 245330, "ref": "org:usdot/245330", "legalName": "BISON TRANSPORT INC", "dbaName": null,
      "domicile": { "city": "WINNIPEG", "state": "MB", "country": "CA" },
      "operation": "interstate", "powerUnits": 1428,
      "links": { "carrier": "/v2/carriers/245330", "vehicles": "/v2/carriers/245330/vehicles" } } ] }
}
```

Costs **1 credit**.

## 2. Read the carrier

`GET /v2/carriers/{dotNumber}` returns two blocks that never mix.

`declared` is what the carrier filed about itself on its latest registration: power units, drivers, annual mileage, whether it carries hazardous materials or passengers. It is self-reported, and `filedOn` says how old it is. Do not divide anything by `declared.mileage` without reading that date.

`observed` is what roadside inspectors and crash reports recorded under the DOT number: distinct units seen, inspections, crashes, first and last seen. Counts, never rates.

A DOT number the road record names but the register does not (a unit's operators can name one) still answers 200: `legalName` and every `declared` field are null, `observed` is the record. 404 is for a DOT number on neither.

```json
{
  "dotNumber": 245330, "legalName": "BISON TRANSPORT INC",
  "domicile": { "city": "WINNIPEG", "state": "MB", "country": "CA" }, "operation": "interstate",
  "declared": { "powerUnits": 1428, "drivers": 1110, "mileage": { "value": 143306767, "year": 2025 },
    "filedOn": "2026-04-22", "registeredOn": "1984-04-12", "hazmat": false, "passengers": false },
  "observed": { "vehicles": 2370, "inspections": 3100, "crashes": 378, "firstSeen": "1995-01-27", "lastSeen": "2026-07-09" }
}
```

The register also holds a street address, a phone number and an officer's name. None of those are served; the domicile is city, state and country.

Costs **5 credits**.

## 3. Walk the fleet

`GET /v2/carriers/{dotNumber}/vehicles` lists every unit an inspector or a crash report put under the DOT number, most recently seen first, with the roles it was seen in, its dates and counts, and a link back to every carrier it ran under.

```json
{
  "dotNumber": 245330,
  "vehicles": { "count": 2370, "items": [
    { "vin": "3AKJHHDR4KSKH9354", "roles": ["power"], "firstSeen": "2022-03-01", "lastSeen": "2026-07-09",
      "inspections": 4, "crashes": 0, "links": { "operators": "/v2/vin/3AKJHHDR4KSKH9354/operators" } } ] },
  "page": { "limit": 100, "nextCursor": "eyJs…" }
}
```

Page with `cursor` until `nextCursor` is null; `limit` goes up to 500. Each page costs **5 credits**. `vehicles.count` is the whole fleet, all pages.

These are observed associations: the unit and the carrier were on one dated row. They are not a confirmed current fleet and not ownership. A unit that changed hands appears under both carriers, each with its own dates, which is the point.

## 4. Walk back from a unit

`GET /v2/vin/{vin}/operators` goes the other way: every carrier a unit was observed running under. There is one item per day an inspection or a crash report put a carrier on the unit, most recent first, so a truck inspected ten times under one carrier is ten items.

```bash
curl "https://api.cardog.app/v2/vin/3HSDZAPR3KN125464/operators?expand=detail" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "Cardog-Version: 2026-10-26"
```

```json
{
  "vin": "3HSDZAPR3KN125464",
  "items": [
    { "id": "3e779a7ef733b442ed32fc2cc06217ae", "observedAt": "2026-06-15", "source": "gov:fmcsa",
      "value": { "dotNumber": 2865124, "ref": "org:usdot/2865124" },
      "detail": { "type": "fmcsa.inspection", "document": "document:inspection/bcee4bd9-1575-5bda-a057-8c8c85c9365f",
        "carrier": { "dotNumber": 2865124, "legalName": "XLI LOGISTICS INC",
          "domicile": { "city": "SURREY", "state": "BC", "country": "CA" }, "operation": "interstate", "powerUnits": 15 } } }
  ],
  "page": { "limit": 100, "nextCursor": null }
}
```

Without `expand` an item is `id`, `observedAt`, `source` and `value`. `expand=detail` adds the record that put the carrier on the unit (`fmcsa.inspection` or `fmcsa.crash`) and the carrier as it stands on the register. This covers the power unit; a trailer's carriers come from `GET /v2/carriers?q={vin}`.

Costs **3 credits** when there is at least one item, 0 when there is none.

## In the SDK

```ts
const found = await client.v2.carriers.search({ q: "bison transport", country: "CA" });
const dot = found.carriers.items[0].dotNumber;
const carrier = await client.v2.carriers.getByDot(dot);
for await (const unit of client.v2.carriers.allVehicles(dot)) {
  const { items } = await client.v2.vin.operators(unit.vin, { expand: ["detail"] });
}
```

## Where the record stops

Coverage is the US federal roadside record: US DOT-regulated commercial vehicles, including the Canadian and Mexican carriers that cross the border. A carrier that only runs inside one province is not here. A unit never stopped at a scale house is not here. No events is not evidence of a clean fleet.


---

Previous: [Parts](https://cardog.app/docs/parts.md) (Vehicle identity)
Next: [Feeds](https://cardog.app/docs/feeds.md) (Vehicle identity)