Federal Contract Vehicles API

A contract vehicle is the indefinite-delivery instrument that individual orders are placed against. FPDS calls them Indefinite Delivery Vehicles (IDVs), and there are five kinds:

The distinction that matters for integration: a vehicle is not an obligation. It is a ceiling and an ordering period. The dollars move on the orders placed against it, which live in the contracts table. A vehicle's own record tells you the most that can be ordered through it (the ceiling) and until when (the ordering period). It does not tell you how much has actually flowed. That is a different query, and this API carries both.

This is the layer that /contracts/* does not answer. Contract award data tells you who won a given order. It does not tell you which vehicle that order rode, who else holds that vehicle and could have bid, or what the vehicle's remaining headroom is. FPDS has all of it; the vehicle records are just buried under their own modification history until you collapse them.

If you only have order-level award data, three real questions go unanswered:

1. Eligibility: could I even have bid. Holding a vehicle is what makes you eligible for the orders placed against it. If you do not hold the IDIQ, you are not in the room when the task order competes. The vehicle layer is where "what would I have needed to hold" lives, and it is knowable in advance.
2. The competed pool: who am I up against. On a multiple-award IDIQ, the competition for every order is the exact pool of firms that hold the vehicle. That pool is a fixed, public list. Pull it and you know your field before the order posts, not after you lose it.
3. Where the money actually flows. A vehicle's ceiling is potential, not spent. A firm can hold a vehicle for years and earn nothing on it. The orders roll-up separates the firms that hold a vehicle from the firms actually being paid through it, so you can tell a live vehicle from a dormant one.

The through-line: the vehicle is often where the real gate is. By the time an order posts, the set of firms that can win it was decided when the vehicle was awarded. Reading vehicles is reading that gate.

Search and single-vehicle detail are on every plan. The holders block is Pro. Same Authorization: Bearer <key> header as everything else.

Search paginates the same way as the rest of the API (limit 1-250, offset ≥ 0, exact total) and returns the same envelope (data, pagination, filters_applied, window, _sources). Sort keys: action_date (default), potential_total_value_of_award, ordering_period_end_date, recipient_name. Field projections: lean (default), expanded, full, or a comma-separated column list via ?fields=. Full parameter and field reference in the API guide.

A vehicle by itself is a stub: a ceiling and a date. The value is in joining it to the orders that ran through it. The API does that join in three places, so you do not have to stitch FPDS tables yourself.

All three endpoints are sourced from FPDS via USAspending ("_sources": ["usaspending_fpds"]). Search returns a lean row per vehicle by default; ?fields=full widens it. Full field-by-field reference in the API guide.

Search response (the largest GWAC by ceiling, real prod query):

{
  "data": [
    {
      "award_id_piid": "47QTCB26D0001",
      "contract_award_unique_key": "CONT_IDV_47QTCB26D0001_4732",
      "idv_type": "GWAC",
      "idv_type_code": "A",
      "prime_award_base_transaction_description": "THE GSA ALLIANT 3 GWAC PROVIDES IT SERVICES-BASED SOLUTIONS THROUGH PERFORMANCE OF A BROAD RANGE OF IT SERVICES THROUGH FLEXIBLE TASK ORDER CONTRACTING TO ELIGIBLE FEDERAL AGENCIES IN ACCORDANCE WITH GSA ORDER OGP 4800.2I.",
      "action_date": "2026-05-06",
      "period_of_performance_start_date": "2026-02-25",
      "ordering_period_end_date": "2036-03-09",
      "potential_total_value_of_award": 999999999999.99,
      "awarding_agency_name": "General Services Administration",
      "awarding_sub_agency_name": "Federal Acquisition Service",
      "recipient_uei": "JCBMLGPE6Z71",
      "recipient_name": "BOOZ ALLEN HAMILTON INC",
      "naics_code": "541512",
      "naics_description": "COMPUTER SYSTEMS DESIGN SERVICES",
      "multiple_or_single_award_idv": "MULTIPLE AWARD",
      "usaspending_permalink": "https://www.usaspending.gov/award/CONT_IDV_47QTCB26D0001_4732/"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 3016, "total_is_estimate": false, "has_next": true },
  "filters_applied": { "idv_type": "GWAC", "sort_by": "potential_total_value_of_award", "sort_order": "desc" },
  "window": { "plan_window_days": null, "earliest_searchable": "1982-05-15", "clamped": false },
  "_sources": ["usaspending_fpds"]
}

The 999999999999.99 ceiling above is real FPDS data. A thin tail of vehicles carries placeholder ceilings (all-nines values, and GSA schedules recorded in the trillions). Those are the source's values and are passed through unchanged rather than rewritten. See Data quirks.

Single-vehicle response (a $7.73B Navy IDIQ plus its orders):

{
  "vehicle": {
    "award_id_piid": "N0003920D0054",
    "idv_type": "IDC",
    "prime_award_base_transaction_description": "SERVICE MANAGEMENT, INTEGRATION, AND TRANSPORT (SMIT)",
    "action_date": "2025-12-08",
    "ordering_period_end_date": "2028-08-04",
    "potential_total_value_of_award": 7729639286.25,
    "awarding_agency_name": "Department of Defense",
    "awarding_sub_agency_name": "Department of the Navy",
    "recipient_uei": "UE9QJD4KK1L6",
    "recipient_name": "LEIDOS, INC.",
    "naics_code": "541512",
    "multiple_or_single_award_idv": "SINGLE AWARD"
  },
  "transaction_rollup": {
    "transaction_count": 70,
    "max_ceiling": 7729639286.25,
    "first_action_date": "2020-02-05",
    "latest_action_date": "2025-12-08",
    "ordering_period_end_date": "2028-08-04",
    "distinct_awardees": 1
  },
  "orders_rollup": {
    "order_count": 16056,
    "distinct_orders": 5988,
    "total_obligated": 1257164494.67,
    "distinct_holders": 1,
    "first_order_date": "2024-10-01",
    "latest_order_date": "2026-02-27"
  },
  "_sources": ["usaspending_fpds"]
}

Read that as: the Navy's SMIT vehicle has a $7.73 billion ceiling, its ordering period runs to August 2028, and $1.26 billion has actually been obligated across 5,988 distinct orders.

Holders response (a single-award IDIQ, so one holder taking 100 percent):

{
  "piid": "N0003920D0054",
  "awardees": [
    {
      "recipient_uei": "UE9QJD4KK1L6",
      "recipient_name": "LEIDOS, INC.",
      "ceiling": 7729639286.25,
      "latest_action_date": "2025-12-08"
    }
  ],
  "awardee_count": 1,
  "earners": [
    {
      "recipient_uei": "UE9QJD4KK1L6",
      "recipient_name": "LEIDOS, INC.",
      "orders": 5988,
      "obligated": 1257164494.67,
      "share_pct": 100.0,
      "latest_order_date": "2026-02-27"
    }
  ],
  "earner_count": 1,
  "_sources": ["usaspending_fpds"]
}

On a multiple-award vehicle you would see several awardees and a share_pct distribution across the earners.

Same passthrough philosophy as the rest of our FPDS data: we do not sanitize source-data weirdness because the weirdness is sometimes the signal. Quirks that have surprised callers in testing:

Each recipe is the actual workflow for one of the three use cases in Why this matters. Copy-paste ready; the Python uses plain requests with no custom client.

import requests
KEY  = "gca_…"
H    = {"Authorization": f"Bearer {KEY}"}
BASE = "https://govconapi.com/api/v1"

def who_holds_this(piid):
    v = requests.get(f"{BASE}/vehicles/{piid}", headers=H).json()
    h = requests.get(f"{BASE}/vehicles/{piid}/holders",
                     headers=H, params={"limit": 250}).json()
    return {
        "vehicle":          v["vehicle"]["prime_award_base_transaction_description"],
        "ceiling":          v["vehicle"]["potential_total_value_of_award"],
        "ordering_ends":    v["vehicle"]["ordering_period_end_date"],
        "obligated_so_far": v["orders_rollup"]["total_obligated"],
        "distinct_orders":  v["orders_rollup"]["distinct_orders"],
        "competed_pool":    h["awardee_count"],   # firms eligible to bid
        "actually_earning": h["earner_count"],    # firms that have won an order
        "top_earners":      h["earners"][:5],
    }

# >>> who_holds_this("N0003920D0054")  # Navy SMIT, Leidos
# {'vehicle': 'SERVICE MANAGEMENT, INTEGRATION, AND TRANSPORT (SMIT)',
#  'ceiling': 7729639286.25, 'ordering_ends': '2028-08-04',
#  'obligated_so_far': 1257164494.67, 'distinct_orders': 5988,
#  'competed_pool': 1, 'actually_earning': 1, …}

def vehicles_in_lane(naics, idv_type="IDC"):
    r = requests.get(f"{BASE}/vehicles/search", headers=H, params={
        "naics":      naics,
        "idv_type":   idv_type,
        "active_only": "true",                       # ordering period still open
        "sort_by":    "potential_total_value_of_award",
        "sort_order": "desc",
        "limit":      50,
    }).json()
    return [
        {"piid":    v["award_id_piid"],
         "holder":  v["recipient_name"],
         "ceiling": v["potential_total_value_of_award"],
         "ends":    v["ordering_period_end_date"]}
        for v in r["data"]
    ]

# vehicles_in_lane("541512")  → active IT-services IDIQs, largest ceiling first
# (swap idv_type="GWAC" or "FSS" to change the instrument)

def utilization(piid):
    v = requests.get(f"{BASE}/vehicles/{piid}", headers=H).json()
    ceiling   = v["vehicle"]["potential_total_value_of_award"]
    obligated = v["orders_rollup"]["total_obligated"]   # FY2025 orders onward
    return {
        "ceiling":       ceiling,
        "obligated":     obligated,
        "distinct_orders": v["orders_rollup"]["distinct_orders"],
        "ordering_ends": v["vehicle"]["ordering_period_end_date"],
        "note": "obligated counts FY2025 orders onward; the vehicle may predate that",
    }

# utilization("N0003920D0054")
#   ceiling=$7.73B  obligated=$1.26B  distinct_orders=5988  ordering_ends=2028-08-04

The recipes above use Python for clarity. For one-shot lookups, the same calls in curl:

The largest GWAC by ceiling:

curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/vehicles/search?idv_type=GWAC&sort_by=potential_total_value_of_award&limit=1"

One vehicle plus its orders roll-up:

curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/vehicles/N0003920D0054"

Who holds a vehicle and who is earning on it (Pro):

curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/vehicles/N0003920D0054/holders?limit=3"

Active IT-services IDIQs in one NAICS:

curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/vehicles/search?naics=541512&idv_type=IDC&active_only=true"

Every vehicle a firm holds (by UEI):

curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/vehicles/search?uei=UE9QJD4KK1L6"

USAspending publishes the same FPDS source data this API serves. Its IDV records are there, but each vehicle's base award and every modification are separate rows, so you build the one-row-per-vehicle collapse yourself, and there is no "who holds this vehicle, and who is earning on it" cursor. Tango, HigherGov, and GovTribe carry contract-vehicle data behind their paid tiers; pricing on those products typically starts above $500/month with seat-based licensing.

The fit: developers and analysts who want vehicle data programmatically alongside the rest of the SAM and FPDS surface (opportunities, orders, entities, exclusions, vendor risk) without building the IDV collapse and the vehicle-to-orders join by hand. If you only need one bulk pull of raw FPDS and have a warehouse to load it into, USAspending is the right tool. If you are building a product that needs the standing set of vehicles, their holders, and their utilization at request time, this is the shortcut.

Vehicle search (/vehicles/search) and single-vehicle detail (/vehicles/{piid}) are on every plan, including Free. They carry the ceiling (potential_total_value_of_award), the ordering period, the transaction roll-up, and the orders roll-up. The holders endpoint (/vehicles/{piid}/holders), which returns the competed pool of awardees and the ranked earners, is Pro ($39/month); Developer and Free keys receive a 402 on that route. Same key, same Authorization: Bearer header across the surface. Rate limit: 1,000 requests/hour per key plus a 60/minute burst cap per IP.

Vehicles are not date-windowed: the full history we carry is searchable on every plan, back to 1982. Orders roll-ups reflect orders placed from FY2025 onward, so a vehicle's own record can date back decades while its obligated total counts only recent throughput.

Subscribe →

Where does this data come from?
FPDS, the Federal Procurement Data System, republished through USAspending.gov. Every response carries "_sources": ["usaspending_fpds"].

What counts as a contract vehicle here?
The five FPDS Indefinite Delivery Vehicle types: IDC (the IDIQ family, the largest group by far), FSS (GSA Federal Supply Schedules), BPA (Blanket Purchase Agreements), GWAC (Government-Wide Acquisition Contracts like SEWP and Alliant), and BOA (Basic Ordering Agreements). Filter with idv_type.

Why one row per vehicle instead of one per transaction?
A vehicle's base award and each modification are separate FPDS rows. Search collapses them so you get one row per vehicle carrying its latest transaction, and pagination.total counts distinct vehicles. Searching idv_type=GWAC returns the GWACs, not the thousands of modification records behind them. This is the opposite of /contracts/search, where each transaction is a distinct obligation and therefore the unit.

Which column is the ceiling?
potential_total_value_of_award. On a vehicle, base_and_all_options_value is populated on only a minority and current_total_value_of_award is never populated, so neither is a usable filter or sort key. ceiling_min / ceiling_max and the ceiling sort all target potential_total_value_of_award. See Data quirks.

Why isn't there a date window on vehicles?
Vehicles are long-lived. A GWAC awarded in 2015 is still the thing you must hold in 2026, and its award date says nothing about its relevance. The full vehicle history is searchable on every plan, back to 1982. Use active_only=true to restrict to vehicles whose ordering period is still open, and date_from / date_to to filter action_date if you want it.

What's the difference between awardees and earners?
awardees are the firms that hold the vehicle, an FPDS IDV record in their name. On a multiple-award IDIQ, that is the competed pool. earners are the firms that have actually been paid through it, ranked by dollars. They are reported separately because a firm can hold a vehicle for years and earn nothing on it; collapsing them would misstate the competitive picture.

Why is share_pct sometimes null?
FPDS records de-obligations as negative amounts, so a vehicle with heavy de-obligations can have a zero or negative net obligation flow. Rather than ship a nonsensical percentage, share_pct is reported as null in that case. Also note that earners is capped by limit and ranked by dollars, so on a large vehicle the shares shown sum to less than 100.

Do the orders roll-ups cover the vehicle's whole life?
No. Orders are carried from FY2025 onward, so orders_rollup and the earners obligations reflect that window. The vehicle's own record and its transaction_rollup can date back decades. On an older vehicle, treat the obligated total as recent throughput, not lifetime spend.

I have an order PIID, not a vehicle PIID. How do I find its vehicle?
Use /contracts/{piid}/vehicle, which resolves an order to the vehicle it rides. /vehicles/{piid} returns 404 if the PIID you pass is an order rather than a vehicle we carry.

Which parts are free and which are Pro?
/vehicles/search and /vehicles/{piid} are on every plan, including Free. /vehicles/{piid}/holders is Pro ($39/month); Developer and Free keys receive a 402. The vehicle record, its ceiling, its ordering period, and its orders roll-up are all available without Pro; the awardees-and-earners breakdown is the Pro layer.

Can I redistribute the data?
The underlying data is public-record federal data. The Pro license covers internal use and product integration. For redistribution as a commercial product, contact us for a custom arrangement.

Ready to integrate? Search and detail are free; Pro adds the holders block at $39/month. Or read the full API reference. Questions about fit: [email protected].