Source catalog
USAspending
Reported award summaries and agency-account spending observations.
Source, grain and coverage
Award-summary amounts are cumulative obligations. Start Date is a performance date, not an action date. Historical trends retain producer-specific methodology.
Retained award summaries contain cumulative obligations. Performance start dates are not transaction action dates. Collection page limits and mixed historical trend methodology can leave incomplete coverage. Account spending and award-summary measures have separate grains.
Collection schedule: Daily.
Records describe public source observations. Missing values remain unknown; historical observations do not establish current status.
Definitions audited . Use source status and the returned watermarks to inspect current collection health.
REST and MCP access
Use a credential with intelligence scope and enable that data domain in your workspace.
curl 'https://www.govbiz.ai/api/v2/catalogue/sources/usaspending-incremental/records?limit=2' \ -H "Authorization: Bearer $GOVBIZ_API_KEY"
The primary dataset is federal_award_summaries. Select another dataset from this source with dataset_id. Supported field names can be used as exact filters; the versioned query endpoint also supports declared ranges and list operators.
Through canonical /mcp, use govbiz_discover_datasets, govbiz_describe_dataset, govbiz_search_records, and govbiz_get_evidence. Cross-source relationships use govbiz_get_related_records and require access to every involved domain.
API contracts · MCP setup · Workspace data domains
Query this source →Federal Award Summaries
federal_award_summaries · Schema 1
One latest retained cumulative award-summary observation per generated_internal_id; performance_start_date is not a transaction action date.
Search modes: structured, lexical. History: Current retained projection; exact historical reconstruction is unsupported.
Measures: record_count. Monetary values use decimal strings with declared units. Unknown amounts do not become zero.
Field definitions and supported filters · 27 fields
| Field | Type / unit | Meaning | Availability and filters |
|---|---|---|---|
agency_code | string | Stored source agency identifier; namespace can be CGAC, FPDS, top-tier or publisher-specific and must be declared.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
agency_name | string | Source agency name; a label whose scope can be department, bureau or office.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
amount | decimal | Reported legacy USAspending subaward amount; not an additive prime-award obligation.Storage and value limits: double: IEEE-754 floating point; not exact cents; reject non-finite public values and preserve precision caveats. | Values can be missingeq, in, is_null, gte, lte |
award_amount | decimal / USD | For active contract award-summary ingestion, Award Amount maps to source total_obligation: cumulative award obligations, not a time-period transaction delta or ceiling.Storage and value limits: double: IEEE-754 floating point; not exact cents; reject non-finite public values and preserve precision caveats. | Values can be missingeq, in, is_null, gte, lte |
award_id | string | Source-specific award identifier; SBIR and USAspending use different namespaces.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
award_type | string | Source instrument category label; decode within the source export version.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
awarding_agency_code | string | Reported awarding agency code identifier; keep its source namespace and buying-versus-funding role.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
awarding_agency_name | string | Reported awarding agency name label; resolve identifiers separately.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
budget_authority_amount | decimal / USD | Agency budget authority/account resources, not only procurement award funding.Storage and value limits: double: IEEE-754 floating point; not exact cents; reject non-finite public values and preserve precision caveats.; null: Arrow null type: this schema variant has no populated value for this column; logical type must come from a contract. | Values can be missingeq, in, is_null, gte, lte |
description | string | Source description in the relation context; distinguish from generated interpretation.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
enacted_amount | decimal / USD | Enacted agency/account amount if separately published.Storage and value limits: null: Arrow null type: this schema variant has no populated value for this column; logical type must come from a contract. | Values can be missingeq, in, is_null, gte, lte |
fiscal_year | integer | Source/derived US federal fiscal year; October 1 starts the following numbered year, with source-specific precision.Storage and value limits: int64: Signed 64-bit integer; values beyond 2^53-1 require a string for JavaScript-safe exactness. | Values can be missingeq, in, is_null, gte, lte |
generated_internal_id | string | USAspending award-summary identifier returned by the search endpoint; not a transaction key.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
gross_outlay_amount | decimal / USD | Reported agency-account gross cash outlay amount; not a company invoice/payment history.Storage and value limits: double: IEEE-754 floating point; not exact cents; reject non-finite public values and preserve precision caveats.; null: Arrow null type: this schema variant has no populated value for this column; logical type must come from a contract. | Values can be missingeq, in, is_null, gte, lte |
ingested_at | string | Producer ingestion timestamp; some relations store ISO text and others timestamp without time zone.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
naics_code | string | Source industry classification code; link with the NAICS edition and declared precision.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ.Require a classification edition; do not join broad prefixes as exact identities. | Values can be missingeq, in, is_null, contains |
obligated_amount | decimal / USD | Reported agency-account obligated amount; not disjoint from prime award obligations.Storage and value limits: double: IEEE-754 floating point; not exact cents; reject non-finite public values and preserve precision caveats.; null: Arrow null type: this schema variant has no populated value for this column; logical type must come from a contract. | Values can be missingeq, in, is_null, gte, lte |
percent_of_total_budget | string | Agency share of a defined total budget, in percent units.Storage and value limits: double: IEEE-754 floating point; not exact cents; reject non-finite public values and preserve precision caveats.; null: Arrow null type: this schema variant has no populated value for this column; logical type must come from a contract. | Values can be missingeq, in, is_null, contains |
period_of_performance_end_date | date | USAspending API summary End Date mapped by this producer.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, gte, lte |
place_of_performance_state | string | Source state/territory of the place of performance; distinct from recipient legal address.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
prime_award_piid | string | Prime contract PIID in a legacy USAspending subaward row; not the subaward identifier.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
recipient_name | string | Reported award recipient label; not a unique entity identifier.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
recipient_parent_name | string | Reported recipient parent label in a legacy subaward record; not verified current corporate ownership.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
recipient_uei | string | Source UEI identifying the recipient participant; missing/empty values cannot support an exact entity join.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ.Logical UEI length is 12; a wider varchar is not broader identity support. | Values can be missingeq, in, is_null, contains |
subaward_id | integer | Legacy USAspending subaward row identifier, scoped to that source endpoint.Storage and value limits: int64: Signed 64-bit integer; values beyond 2^53-1 require a string for JavaScript-safe exactness. | Values can be missingeq, in, is_null, gte, lte |
subaward_number | string | Subaward reference within a prime award, not globally unique alone.Storage and value limits: large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, contains |
performance_start_date | date | Award period-of-performance Start Date; not a transaction/action date.Storage and value limits: date32[day]: Calendar date without time of day or timezone; source precision can be month/quarter instead.; large_string: No declared field-length cap here; API/output budgets must apply; empty and null differ. | Values can be missingeq, in, is_null, gte, lte |
Agency Spending Trends
agency_spending_trends · Schema 1
One retained legacy derived amount/count per agency_code, naics_code and fiscal_year; producer methodology can mix cumulative award summaries and historical inputs.
Search modes: structured. History: Current retained projection; exact historical reconstruction is unsupported.
Measures: record_count. Monetary values use decimal strings with declared units. Unknown amounts do not become zero.
Field definitions and supported filters · 7 fields
| Field | Type / unit | Meaning | Availability and filters |
|---|---|---|---|
agency_code | string | Stored source agency identifier; namespace can be CGAC, FPDS, top-tier or publisher-specific and must be declared.Storage and value limits: Maximum 10 characters; identifier rules can be narrower. | Values can be missingeq, in, is_null, contains |
naics_code | string | Source industry classification code; link with the NAICS edition and declared precision.Storage and value limits: Maximum 6 characters; identifier rules can be narrower.Require a classification edition; do not join broad prefixes as exact identities. | Values can be missingeq, in, is_null, contains |
fiscal_year | integer | Source/derived US federal fiscal year; October 1 starts the following numbered year, with source-specific precision.Storage and value limits: Signed 32-bit integer; logical domain constraints can be narrower. | Values can be missingeq, in, is_null, gte, lte |
total_obligations | decimal / USD | Current producer sums award-summary cumulative obligations grouped by award Start Date fiscal year; this is not uniform action-date period spending. Legacy producer rows may use a different grain.Storage and value limits: Precision 15, scale 2; absolute value below 10^13; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
award_count | integer | Producer-defined count; current NAICS summary producer counts non-null award amounts, not uniformly contract actions.Storage and value limits: Signed 32-bit integer; logical domain constraints can be narrower. | Values can be missingeq, in, is_null, gte, lte |
avg_award_value | decimal / USD | Producer mean award amount at its own grain; not comparable before methodology normalization.Storage and value limits: Precision 15, scale 2; absolute value below 10^13; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
refreshed_at | datetime | Time a producer refreshed this row; not the underlying source record date.Storage and value limits: Instant with timezone only if declared; otherwise local/producer time must be explicitly interpreted. Do not invent clock precision. | Values can be missingeq, in, is_null, gte, lte |
Agency Account Spending
agency_account_spending · Schema 1
One retained agency-account spending summary per agency_code and fiscal_year; these are account-level measures rather than individual award actions.
Search modes: structured, lexical. History: Current retained projection; exact historical reconstruction is unsupported.
Measures: record_count. Monetary values use decimal strings with declared units. Unknown amounts do not become zero.
Field definitions and supported filters · 9 fields
| Field | Type / unit | Meaning | Availability and filters |
|---|---|---|---|
agency_code | string | Stored source agency identifier; namespace can be CGAC, FPDS, top-tier or publisher-specific and must be declared.Storage and value limits: Maximum 20 characters; identifier rules can be narrower. | Values can be missingeq, in, is_null, contains |
fiscal_year | integer | Source/derived US federal fiscal year; October 1 starts the following numbered year, with source-specific precision.Storage and value limits: Signed 32-bit integer; logical domain constraints can be narrower. | Values can be missingeq, in, is_null, gte, lte |
agency_name | string | Source agency name; a label whose scope can be department, bureau or office.Storage and value limits: Maximum 200 characters; identifier rules can be narrower. | Values can be missingeq, in, is_null, contains |
budget_authority_amount | decimal / USD | Agency budget authority/account resources, not only procurement award funding.Storage and value limits: Precision 18, scale 2; absolute value below 10^16; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
obligated_amount | decimal / USD | Reported agency-account obligated amount; not disjoint from prime award obligations.Storage and value limits: Precision 18, scale 2; absolute value below 10^16; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
gross_outlay_amount | decimal / USD | Reported agency-account gross cash outlay amount; not a company invoice/payment history.Storage and value limits: Precision 18, scale 2; absolute value below 10^16; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
enacted_amount | decimal / USD | Enacted agency/account amount if separately published.Storage and value limits: Precision 18, scale 2; absolute value below 10^16; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
percent_of_total_budget | decimal | Agency share of a defined total budget, in percent units.Storage and value limits: Precision 8, scale 4; absolute value below 10^4; rounding on assignment; checks can narrow the range. | Values can be missingeq, in, is_null, gte, lte |
ingested_at | datetime | Producer ingestion timestamp; some relations store ISO text and others timestamp without time zone.Storage and value limits: Instant with timezone only if declared; otherwise local/producer time must be explicitly interpreted. Do not invent clock precision. | Values can be missingeq, in, is_null, gte, lte |