> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Federal Awards

> Look up the US federal contracts or grants a recipient holds, largest first.

Look up the US federal contracts or grants held by a recipient, found by its name or its Unique Entity Identifier (UEI), largest first. Give exactly one of `recipient` and `uei`, and `kind` (`contracts` or `grants`): contracts and grants are separate groups and cannot be mixed in one call. Each award has its identifier, recipient name and UEI, total value in US dollars, start and end dates, awarding agency and sub-agency, description and a link to the award record; contracts also carry the industry (NAICS) and product or service (PSC) codes. Searches by date: returns the awards the source lists for the period from `active_after` to `active_before` (default: the last three years up to today; nothing before 2007-10-01). That is not the same as awards running in the period: the source does not limit rows to awards that overlap it, so an award may have ended before the period or start after it. Read each row's start and end dates to judge whether it is current. A name is a text match, so similarly named recipients come back too: tell them apart by the recipient name and UEI on each row, and prefer the UEI when you have it. `has_more` is true when more awards exist than `limit`. No awards is a completed result with an empty list. Covers US federal awards only.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="recipient" type="string">
  Recipient name, for example LOCKHEED MARTIN CORPORATION. A text match: similarly named recipients are returned too. 3 to 120 characters.
</ParamField>

<ParamField body="uei" type="string">
  The recipient's 12-character Unique Entity Identifier. Preferred over a name. A UEI is 12 letters and digits.
</ParamField>

<ParamField body="kind" type="string" required>
  Which group of awards to list: contracts, or grants. One of `contracts`, `grants`.
</ParamField>

<ParamField body="active_after" type="string">
  Start of the period to search, YYYY-MM-DD, not before 2007-10-01. Default: three years before active\_before. Use YYYY-MM-DD.
</ParamField>

<ParamField body="active_before" type="string">
  End of the period to search, YYYY-MM-DD. Default: today. Use YYYY-MM-DD.
</ParamField>

<ParamField body="limit" type="integer">
  Most awards to return, largest first (1 to 25, default 10). From 1 to 25. Defaults to `10`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `company_federal_awards`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US Department of the Treasury`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.kind" type="string">
  Kind.
</ResponseField>

<ResponseField name="data.result.has_more" type="boolean">
  True when more awards matched than were returned.
</ResponseField>

<ResponseField name="data.result.awards" type="object[]">
  Largest first; empty when the recipient holds none in the period.
</ResponseField>

<ResponseField name="data.result.awards[].award_id" type="string">
  The award's identifier (contract number or assistance award number). `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].recipient_name" type="string">
  The recipient as named on the award; a name search also returns similarly named recipients. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].recipient_uei" type="string">
  The recipient's Unique Entity Identifier; use it to tell recipients apart. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].amount_usd" type="number">
  Total value of the award in US dollars. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].start_on" type="string">
  Start date of the award, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].end_on" type="string">
  End date of the award, YYYY-MM-DD, when it has one. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].agency" type="string">
  Awarding agency. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].sub_agency" type="string">
  Awarding sub-agency. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].description" type="string">
  Description. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].industry_code" type="string">
  NAICS code (contracts only). `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].industry" type="string">
  NAICS description (contracts only). `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].product_code" type="string">
  Product or service code, PSC (contracts only). `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].product" type="string">
  Product or service description (contracts only). `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.awards[].url" type="string">
  Link to the award record. `null` when the source gives no value.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-federal-awards \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "recipient": "LOCKHEED MARTIN CORPORATION",
      "kind": "contracts",
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/company-federal-awards", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "recipient": "LOCKHEED MARTIN CORPORATION",
      "kind": "contracts",
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/company-federal-awards', {
    recipient: 'LOCKHEED MARTIN CORPORATION',
    kind: 'contracts',
    limit: 1
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "company_federal_awards",
      "result": {
        "kind": "contracts",
        "has_more": true,
        "awards": [
          {
            "award_id": "N0001917C0001",
            "recipient_name": "LOCKHEED MARTIN CORPORATION",
            "recipient_uei": "EXAMPLEUEI01",
            "amount_usd": 35135514910.2,
            "start_on": "2017-11-17",
            "end_on": "2031-03-31",
            "agency": "Department of Defense",
            "sub_agency": "Department of the Navy",
            "description": "F-35 lightning II aircraft",
            "industry_code": "336411",
            "industry": "Aircraft Manufacturing",
            "product_code": "1510",
            "product": "Aircraft, Fixed Wing",
            "url": "https://www.usaspending.gov/award/CONT_AWD_N0001917C0001_9700_-NONE-_-NONE-"
          }
        ]
      },
      "evidence": {
        "source": "US Department of the Treasury",
        "source_kind": "public",
        "retrieved_at": "2026-01-15T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.01 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.