# AlphaLoops FMCSA Carrier Data API

> Fleet intelligence for freight. FMCSA motor-carrier data on 2.7M U.S. carriers — profiles with
> 200+ fields, operating authority and insurance history, VIN-level fleet equipment, roadside
> inspections and violations, crashes, corporate-connection graphs, decision-maker contacts, and
> fraud/risk signals. Available as a REST API, a hosted MCP server, published Python/TypeScript
> SDKs and a CLI.

GENERATED BY API EVANGELIST — this file is NOT published by AlphaLoops. The provider advertises
https://runalphaloops.com/llms.txt, but that URL returns HTTP 200 carrying the marketing site's
single-page-app HTML shell (6,831 bytes, byte-identical to the response for /apis.json and every
/.well-known/ path), not an llms.txt document. This file was generated on 2026-08-11 from the
provider's live OpenAPI 3.1 and public documentation so agents have something machine-readable.
Provenance: method=generated, source=https://runalphaloops.com/openapi.json

## Base facts

- Provider: AlphaLoops, Inc. — https://runalphaloops.com
- API base URL: https://api.runalphaloops.com
- Auth: `Authorization: Bearer <api_key>` (static key; issued by sales, not self-service)
- Contract: OpenAPI 3.1.0 — https://runalphaloops.com/openapi.json (live, 25 operations, 53 schemas)
- All endpoints under `/v1/`. Read-only: 23 GET, 2 POST (both are searches).
- Rate limits: 60 req/min and 5,000 req/day (Enterprise REST tier)
- Rate-limit headers on EVERY response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
  `X-RateLimit-Reset`, `X-DailyLimit-Limit`, `X-DailyLimit-Remaining`, `X-DailyLimit-Reset`.
  On 429, honour `Retry-After`.
- Errors: `{"error": "...", "message": "..."}` — not RFC 9457. Branch on HTTP status; the
  `error` string has no published value set.
- CORS: `OPTIONS -> 204`, `Access-Control-Allow-Origin: *`. Note the only credential is a static
  unscoped bearer key, so browser use exposes it.

## Documentation

- [API reference](https://runalphaloops.com/fmcsa-api/docs): Full endpoint reference, parameter tables, response examples, error codes, rate limits.
- [FMCSA API overview](https://runalphaloops.com/fmcsa-api): Product page for the API.
- [FMCSA data guide](https://runalphaloops.com/fmcsa-api/guide): Background on FMCSA data itself.
- [OpenAPI 3.1 specification](https://runalphaloops.com/openapi.json): The machine-readable contract.
- [MCP server reference](https://runalphaloops.com/mcp): Endpoint, tool inventory, transport, versioning, tiers.
- [Pricing](https://runalphaloops.com/pricing): Platform tiers and add-on ladders.
- [What's New](https://runalphaloops.com/whats-new): Dated product changelog.
- [Security](https://runalphaloops.com/security): Security posture and vulnerability disclosure.
- [Trust Center](https://trust.runalphaloops.com/): Vanta-hosted (JS-rendered).
- [Status](https://status.runalphaloops.com): Uptime and incidents.
- [Support](https://runalphaloops.com/support)
- [Contact / get an API key](https://runalphaloops.com/contact)

## MCP server

- Endpoint: `https://mcp-freight.runalphaloops.com/mcp`
- Type: hosted remote, MCP URL transport, HTTPS + SSE. No local install.
- Auth: `Authorization: Bearer <api_key>`. An unauthenticated `tools/list` returns 401 with a
  `WWW-Authenticate` challenge, so live tool schemas are not publicly readable.
- OAuth metadata (RFC 8414): `https://mcp-freight.runalphaloops.com/.well-known/oauth-authorization-server`
  — authorization-code + refresh-token, PKCE S256, open dynamic client registration.
- Versioning: `X-AlphaLoops-Version` header pins tool schemas; omitting it floats to latest.
  Breaking changes get a new version with a 90-day deprecation window.
- Advertised as 30+ tools; 24 are named publicly across six categories:
  - Lookup: `carrier_lookup`, `carrier_lookup_by_mc`, `carrier_overview`, `carrier_authority`
  - Search: `carrier_search`, `carrier_filtered_query`, `carrier_similar`, `list_prospects`
  - Score: `carrier_score`, `list_create`, `list_enrich`
  - Safety: `inspections_list`, `inspection_violations`, `crashes_list`, `fleet_trucks`, `fleet_trailers`
  - Risk: `carrier_risk_signals`, `carrier_connections`, `watchlist_mc_sales`, `watchlist_subscribe`, `carrier_news`
  - Contact: `contacts_search`, `contact_enrich`, `contacts_enrich_bulk`

18 of those 24 tools map onto a REST operation whose parameters ARE the tool's real input schema —
the mapping is published in this repo at `mcp/alphaloops-tool-crosswalk.yml`.

## REST operations

Carrier lookup and search:
- `getCarrierByDot` — GET /v1/carriers/{dot_number} — full profile, 200+ fields. Supports `?fields=`.
- `getCarrierByMc` — GET /v1/carriers/mc/{mc_number} — same profile by MC/MX docket. Supports `?fields=`.
- `getCarrierOverview` — GET /v1/carriers/{dot_number}/overview — condensed summary.
- `searchCarriers` — GET /v1/carriers/search — fuzzy name match. `company_name` required; `limit` max 50.
- `queryCarriers` — POST /v1/carriers/query — advanced filter: include/exclude, ranges, arrays, geo-radius, sorting, field projection.
- `getSimilarCarriers` — GET /v1/carriers/{dot_number}/similar — embedding-based lookalikes.

Authority and insurance:
- `getCarrierAuthority` — GET /v1/carriers/{dot_number}/authority — grants, revocations, reinstatements.
- `getCarrierInsurance` — GET /v1/carriers/{dot_number}/insurance
- `getCarrierInsuranceByMc` — GET /v1/carriers/mc/{mc_number}/insurance

Fleet and equipment:
- `getCarrierTrucks` — GET /v1/carriers/{dot_number}/trucks — VIN-level.
- `getCarrierTrailers` — GET /v1/carriers/{dot_number}/trailers — VIN-level.
- `lookupVins` — GET /v1/vins
- `lookupVinsBatch` — POST /v1/vins
- `getVinInspectionHistory` — GET /v1/inspections/vin/{vin}

Safety:
- `getCarrierInspections` — GET /v1/carriers/{dot_number}/inspections
- `getInspectionViolations` — GET /v1/inspections/{inspection_id}/violations
- `getCarrierCrashes` — GET /v1/carriers/{dot_number}/crashes — severity: FATAL, INJURY, TOW, PROPERTY_DAMAGE.

Risk and signals:
- `getCarrierRiskSignals` — GET /v1/carriers/{dot_number}/risk-signals
- `getCarrierConnections` — GET /v1/carriers/{dot_number}/connections — corporate graph (nodes + edges).
- `getCarrierMcSales` — GET /v1/carriers/{dot_number}/mc-sales — authority-for-sale signal.
- `getCarrierEquipmentForSale` — GET /v1/carriers/{dot_number}/equipment-for-sale
- `getCarrierTimeline` — GET /v1/carriers/{dot_number}/timeline — change events with old/new values.
- `getCarrierNews` — GET /v1/carriers/{dot_number}/news

Contacts (metered):
- `searchContacts` — GET /v1/contacts/search — levels: c_suite, vp, director, manager. CAN RETURN 202 (async; retry after a delay).
- `enrichContact` — GET /v1/contacts/{contact_id}/enrich — 1 credit per NEW enrichment, cached free. 402 when exhausted. Balance in `X-Enrichment-Credits-Remaining` and the body `credits` object.

## Gotchas an agent must know

- **Pagination is not uniform.** `trucks`, `trailers`, `inspections`, `authority` and `timeline`
  use `offset`/`limit`. Everything else uses `page`/`limit`.
- **The results array is named differently per endpoint**: `results`, `trucks`, `trailers`,
  `inspections`, `violations`, `crashes`, `articles`, `contacts`, `events`, `equipment`,
  `similar_carriers`, `insurance`.
- **`?fields=` only works on the two carrier-profile endpoints.** `queryCarriers` takes its own
  `fields` array in the request body.
- **404 means the carrier does not exist. An empty sub-resource returns 200 with an empty array** —
  do not report "not found" for a carrier with no trucks on file.
- **202 from `searchContacts` is a success**, not an error. No job id or poll interval is
  published; back off progressively.
- **Enrichment costs a credit.** Check remaining balance before batching; 402 is terminal.
- **No idempotency key** on any surface. The REST API is read-only so this is low risk, but MCP
  tools that write (`list_create`, `watchlist_subscribe`) and metered enrichment have no replay
  protection.
- **`getCarrierMcSales` returns 200/401/429 only** — no 404 — unlike every other carrier sub-resource.

## SDKs and tools

- Python SDK: `pip install alphaloops-freight-sdk` (0.2.2, 2026-04-19) — https://pypi.org/project/alphaloops-freight-sdk/
- TypeScript SDK: `npm install alphaloops-freight-sdk` (0.2.2, 2026-04-19) — https://www.npmjs.com/package/alphaloops-freight-sdk
- CLI `loopsh`: `pip install alphaloops-freight-cli` (0.4.0, 2026-03-11) — https://pypi.org/project/alphaloops-freight-cli/
- n8n node: `n8n-nodes-alphaloops-freight` (0.1.18, 2026-04-29)
- Source: https://github.com/RunAlphaLoop/freight-sdk · https://github.com/RunAlphaLoop/freight-cli
- Provider-authored agent guide: https://github.com/RunAlphaLoop/freight-cli/blob/HEAD/alphaloops/AGENTS.md

Note the SDKs and CLI cover only five resource groups (carriers, contacts, crashes, fleet,
inspections) — roughly half the REST surface. Insurance, timeline, mc-sales, equipment-for-sale,
connections, risk-signals, similar, overview and the VIN family have no SDK or CLI coverage. Call
those over HTTP directly.

## Optional

- [Integrations](https://runalphaloops.com/integrations): Salesforce, HubSpot, Microsoft Dynamics 365, n8n, Zapier, MCP.
- [Research](https://research.runalphaloops.com): Provider research site.
- [Guides](https://runalphaloops.com/guides): Carrier vetting, chameleon-carrier detection, MC-number sales, FMCSA prospecting.