> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Federal Awards (USAspending) > US federal award exposure for an entity — USAspending prime awards (contracts + grants) resolved to the entity spine. Look a subject up three ways (at least one is required): a resolved spine `entity_id` (`entity=`), a SAM.gov Unique Entity Identifier (`uei=`), or a fuzzy recipient name (`recipient=`). Returns an aggregate `summary` (total obligated USD, award + recipient counts) with a per-UEI `recipient_rollups` breakdown (top 25 by obligated USD, each with its awarding agencies and first/last action dates), plus the recent `awards` timeline — every row cited to its USAspending permalink. **D&B carve-out:** keyed on the SAM.gov UEI only — Dun & Bradstreet's DUNS number and corporate-family (parent) tree are never ingested or surfaced. Plan-gated: requires the `can_use_gov` entitlement (Markets plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Reads are bounded key-prefix lookups on the current award snapshot (no all-time scan). ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/gov/awards openapi: 3.0.3 info: title: GDELT Cloud API v2 version: 2.0.0 description: >- Clean v2 REST API for generated GDELT Cloud structured Events, clustered Stories, linked Entities, summaries, admin1 discovery, significance ranking, and paginated article evidence. Event significance is a family-scoped weighted blend, renormalized so every event family spans a true 0-1: each event's raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured its term AND its 0.20 weight are both dropped. The four CAMEO+ metrics are rubric scores produced by published formulas - ordinal ranking signals, not measurements, probabilities, or predicted price moves. goldstein_scale is one canonical public metric, populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful. Story linked_event_count is a Story-to-Event link aggregate, not a distinct Event total. servers: - url: https://gdeltcloud.com description: Production - url: http://localhost:3000 description: Local development security: - ApiKeyAuth: [] tags: - name: Events description: Coded CAMEO+ / conflict events — search, fetch, and summarize. - name: Stories description: Clustered narratives (stories) and their articles. - name: Entities description: >- People & organizations — resolve a name to an entity, then fetch its profile and tone. - name: Geography description: Admin-1 geography lookups. - name: Energy description: Global Energy Monitor assets + ownership registry. - name: Facilities description: >- Unified physical-asset directory — GEM energy assets + World Port Index ports + Epoch AI data centers on one keyed surface, resolved to spine owners. Plan-gated (Analyst plan and up). - name: Screening and Reference description: >- Restricted-party lists, screening, and ownership-chain exposure. Plan-gated (`can_use_screening` / `can_use_exposure`). - name: China description: >- China overseas development finance (AidData GCDF). Plan-gated (`can_use_china`). - name: Media Intelligence description: >- Entity tone (`can_use_tone`) and Share of Voice (`can_use_share_of_voice`) are plan-gated. Social signal remains an admin-only preview. - name: Filings description: >- SEC EDGAR filings, XBRL financials, and AI-extracted relations. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above. - name: Macro Finance description: >- FRED economic time series (catalog, point-in-time observations, releases). Plan-gated (`can_use_macro`). - name: Maritime description: >- AIS-derived vessel-flow signals across maritime chokepoints — chokepoint transits, last-known vessel positions, carriers, dwell, and AIS-dark gaps. Plan-gated (`can_use_maritime`). - name: Briefs description: Source-backed monitoring briefs. paths: /api/v2/gov/awards: get: tags: - Government summary: Federal Awards (USAspending) description: >- US federal award exposure for an entity — USAspending prime awards (contracts + grants) resolved to the entity spine. Look a subject up three ways (at least one is required): a resolved spine `entity_id` (`entity=`), a SAM.gov Unique Entity Identifier (`uei=`), or a fuzzy recipient name (`recipient=`). Returns an aggregate `summary` (total obligated USD, award + recipient counts) with a per-UEI `recipient_rollups` breakdown (top 25 by obligated USD, each with its awarding agencies and first/last action dates), plus the recent `awards` timeline — every row cited to its USAspending permalink. **D&B carve-out:** keyed on the SAM.gov UEI only — Dun & Bradstreet's DUNS number and corporate-family (parent) tree are never ingested or surfaced. Plan-gated: requires the `can_use_gov` entitlement (Markets plan and up); non-entitled plans receive 403 PLAN_REQUIRED. Reads are bounded key-prefix lookups on the current award snapshot (no all-time scan). operationId: get-gov-awards-v2 parameters: - name: entity in: query required: false schema: type: string description: >- A resolved spine entity id (`e_…` / `wiki:…` / `cik:…`). A bare name is rejected with 400 INVALID_ENTITY_ID — resolve it first via GET /api/v2/search. Returns that entity's federal awards. example: e_7e9bc31057830fbf - name: uei in: query required: false schema: type: string description: A SAM.gov Unique Entity Identifier (12-char). Case-insensitive. example: K8YHEXAMPLE01 - name: recipient in: query required: false schema: type: string description: >- Fuzzy (case-insensitive substring) recipient-name match — no id required. example: Lockheed - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 100 description: >- Award-timeline rows to return (max 500). The summary and recipient_rollups aggregate across ALL matching awards regardless of this cap. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GovAwardsResponse' examples: awards: value: query: entity: null uei: null recipient: Lockheed limit: 25 summary: recipients: 34 total_awards: 4821 total_obligated: 342118904233 recipient_rollups: - recipient_uei: K8YHEXAMPLE01 recipient_name: LOCKHEED MARTIN CORPORATION entity_id: e_7e9bc31057830fbf award_count: 3120 total_obligated: 301884221190 agency_count: 12 top_agencies: - Department of Defense - National Aeronautics and Space Administration - Department of State first_action_date: '1998-03-11' last_action_date: '2026-06-28' awards: - award_id: CONT_AWD_FA860124C0001_9700 recipient_name: LOCKHEED MARTIN CORPORATION recipient_uei: K8YHEXAMPLE01 entity_id: e_7e9bc31057830fbf award_amount: 1200000000 awarding_agency: Department of Defense awarding_sub_agency: Department of the Air Force award_group: contract award_type: DEFINITIVE CONTRACT action_date: '2026-06-28' end_date: '2031-06-27' source_url: >- https://www.usaspending.gov/award/CONT_AWD_FA860124C0001_9700 meta: source: gov.usaspending_awards attributions: - source: USAspending.gov source_url: https://www.usaspending.gov/ license: US Public Domain note: >- Federal award data is US public domain. Keyed on SAM.gov UEI; Dun & Bradstreet fields (DUNS, corporate-family tree) are excluded by license. '400': description: >- Missing subject (need entity / uei / recipient), or a bare name passed to entity=. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: success: false error: >- gov "entity"/"entity_id" must be a resolved entity id (e.g. e_… or wiki:…). "Lockheed" looks like a name — resolve it via GET /api/v2/search?q=Lockheed and pass its entity_id, or use recipient= for a fuzzy recipient-name match, or uei= for a SAM.gov UEI. code: INVALID_ENTITY_ID '401': description: 'API key required. Include: Authorization: Bearer gdelt_sk_...' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: success: false error: >- API key required. Include: Authorization: Bearer gdelt_sk_... code: MISSING_API_KEY '403': description: >- The caller's plan does not carry the can_use_gov entitlement (Markets plan and up). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: success: false error: >- Government exposure (federal awards) is not included in your plan. Upgrade at https://gdeltcloud.com/pricing to unlock it. code: PLAN_REQUIRED '429': description: Rate limit or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: success: false error: Rate limit or quota exceeded. code: RATE_LIMITED '500': description: Failed to fetch government exposure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: success: false error: Failed to fetch government exposure. code: INTERNAL_ERROR security: - ApiKeyAuth: [] components: schemas: GovAwardsResponse: type: object description: >- Entity federal-award exposure — USAspending prime awards keyed on SAM.gov UEI, resolved to the entity spine. properties: query: type: object properties: entity: type: string nullable: true uei: type: string nullable: true recipient: type: string nullable: true limit: type: integer summary: type: object properties: recipients: type: integer description: Distinct recipient UEIs across all matching awards. total_awards: type: integer description: Total matching awards (not capped by limit). total_obligated: type: number description: Sum of obligations across all matching awards, in USD. recipient_rollups: type: array items: type: object properties: recipient_uei: type: string recipient_name: type: string entity_id: type: string description: >- Resolved spine entity id; empty string when the recipient did not resolve to the spine. award_count: type: integer total_obligated: type: number description: Sum of award obligations for this UEI, in USD. agency_count: type: integer top_agencies: type: array items: type: string description: Up to 10 distinct awarding agencies for this UEI. first_action_date: type: string format: date last_action_date: type: string format: date description: Per-UEI rollup, top 25 by obligated USD. awards: type: array items: type: object properties: award_id: type: string description: USAspending award unique key (the permalink id). recipient_name: type: string recipient_uei: type: string entity_id: type: string description: Resolved spine entity id; empty string when unresolved. award_amount: type: number description: Obligated amount for this award, in USD. awarding_agency: type: string awarding_sub_agency: type: string award_group: type: string description: contract | grant | loan | direct_payment | other. award_type: type: string action_date: type: string format: date description: Latest action date for the award. end_date: type: string description: Period-of-performance end date; empty string when unknown. source_url: type: string description: USAspending permalink for the award. description: Recent award timeline (up to limit), newest first. meta: type: object properties: source: type: string attributions: type: array items: type: object properties: source: type: string source_url: type: string license: type: string note: type: string note: type: string nullable: true description: Present only when the result set is empty. cross_source: nullable: true allOf: - $ref: '#/components/schemas/GovCrossSource' ErrorResponse: type: object properties: success: type: boolean enum: - false error: type: string code: type: string details: type: object description: >- Recoverable validation context when available, such as param, invalid_value, accepted_values, nearest_values, and a corrected example. additionalProperties: true GovCrossSource: type: object description: >- Cross-source fusion for the primary resolved entity — its footprint beyond this endpoint (foreign-agent status, SEC filer, facilities owned) + headline flags. Null when there is no cross-source signal. properties: entity_id: type: string federal_awards: type: object nullable: true properties: awards: type: integer total_obligated: type: number foreign_agent: type: object nullable: true description: This entity AS a US registrant (foreign agent). properties: registrations: type: integer foreign_principals: type: integer sanctioned_principals: type: integer description: Foreign principals it represents that are on a sanctions list. countries: type: array items: type: string foreign_principal_of: type: object nullable: true description: >- This entity AS a foreign principal — the US firms registered to represent it. properties: us_registrants: type: integer sec_filer: type: boolean facilities_owned: type: integer flags: type: array items: type: string description: >- Headline cross-flags: federal_contractor_and_foreign_agent, foreign_agent_for_sanctioned_entity. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````