US Brand Federal Award Snapshot - USAspending Prime Contract Transactions

Given one exact USAspending recipient ID, return one bounded snapshot containing up to 25 prime contract transactions for that exact source recipient and date window.

This is a machine-first, point-in-time federal award snapshot for company and government-intelligence workflows. It uses the official USAspending API, verifies the child recipient identity with the exact recipient ID and UEI, and returns deterministic JSON without a browser, LLM, API key, or buyer-supplied URL.

What you get

• Exact recipient attribution - V1 accepts one lowercase USAspending child recipient ID ending in -C; returned transactions must match both that ID and the verified recipient UEI.
• Prime contract transactions - the first source page can return up to 25 transactions for award type codes A, B, C, and D, sorted by action date descending with deterministic tie-breakers.
• Official source freshness - the snapshot includes sourceAsOf, sourceAsOfRaw, the queried date window, and the canonical USAspending recipient detail URL.
• Closed machine output - one successful Dataset row contains recipient, awards, resultCount, partial, and sourceStats; every run also writes a compact closed OUTPUT envelope.
• Bounded execution - three serialized source operations, one first page, strict response-size limits, and a deterministic retry policy make the Actor suitable for automated pipelines.

The snapshot is not a change feed, ownership proof, legal conclusion, or complete award history. A missing transaction does not prove that the recipient has no federal relationship.

How to run it

Paste an exact child recipient ID and an inclusive date window into the Actor input. This is a useful Apple example from the accepted contract:

{
  "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C",
  "startDate": "2026-07-01",
  "endDate": "2026-08-04",
  "maxResults": 10,
  "requestId": "prefill-apple-contracts-2026-08"
}

recipientId is the selector. A legal name, brand name, UEI, legacy business identifier, parent ID, keyword, award group, URL, proxy, token, or API key is not accepted as input.

Input

Field	Required	Limits and meaning
recipientId	yes	Lowercase child recipient ID matching ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-C$. Parent -P and recipient -R IDs are rejected in V1.
startDate	yes	Strict YYYY-MM-DD; no earlier than 2007-10-01.
endDate	yes	Strict YYYY-MM-DD; must be on or after startDate and no later than the Actor's UTC run date.
maxResults	no	Integer from 1 to 25; default 10.
requestId	no	Correlation metadata only; 1 to 80 ASCII characters matching ^[A-Za-z0-9._:-]+$. It is not replay or deduplication state.

The inclusive date span is at most 366 days. Input is closed: extra properties fail before any source request, Dataset row, or result-found event.

Source and exact request plan

The only source is the official USAspending API at api.usaspending.gov. V1 uses direct Apify egress, no API key, and the fixed User-Agent ZininApifyFederalAwardSnapshot/1.0 (https://zinin.ai). The buyer cannot select an endpoint, host, path, method, redirect, request body, proxy, or arbitrary URL.

Each valid, authorized run performs these operations in order:

1. GET /api/v2/recipient/{percent-encoded recipientId}/
2. GET /api/v2/awards/last_updated/
3. POST /api/v2/search/spending_by_transaction/ with the fixed exact-recipient filter and the requested date window

Only page 1 is requested. partial is true only when the valid source response says page_metadata.hasNext === true; page 2 is never fetched.

Reference source contracts: USAspending endpoint documentation, recipient API contract, and spending-by-transaction API contract.

Exact limits

• Maximum 3 source operations and 6 HTTP attempts total; at most two attempts per operation.
• 8 seconds per attempt and 45 seconds from the first source request, measured with a monotonic clock.
• Retry only for 429, 502, 503, 504, connection reset, or timeout. The default delay is 500 ms for 429 and 250 ms for other retryable outcomes; an integer Retry-After from 0 to 2 seconds takes precedence for 429.
• Maximum decoded response size is 1 MiB per operation and 3 MiB total.
• Accepted response media types are application/json and application/*+json; malformed, oversized, redirected, or otherwise out-of-contract responses fail closed.
• Maximum successful output is 25 exact-attributed transactions from the first page.
• No browser, login, cookies, proxy, BYOK credential, LLM, bulk export, arbitrary URL, or cross-run state.

Output

Successful OUTPUT envelope

Every run attempts one compact OUTPUT KVS record. A successful envelope points to the run Dataset; non-success envelopes have found: false, resultCount: 0, partial: false, and datasetId: null.

{
  "schemaVersion": "1.0",
  "actor": "us-brand-federal-award-snapshot",
  "requestId": "prefill-apple-contracts-2026-08",
  "status": "SUCCEEDED",
  "found": true,
  "resultCount": 1,
  "partial": false,
  "datasetId": "your-run-dataset-id",
  "sourceStats": {
    "operations": 3,
    "attempts": 3,
    "decodedBytes": 12345
  },
  "message": "Exact recipient snapshot returned."
}

sourceStats is intentionally reduced to exactly operations, attempts, and decodedBytes. It has no row-count, identity-mismatch, invalid-row, or duplicate hasNext fields.

Successful Dataset row

The paid Dataset row is one bounded snapshot. This sample follows the current reduced closed schema:

{
  "schemaVersion": "1.0",
  "actor": "us-brand-federal-award-snapshot",
  "requestId": "prefill-apple-contracts-2026-08",
  "found": true,
  "queriedAt": "2026-08-04T00:00:00.000Z",
  "sourceAsOf": "2026-08-03",
  "sourceAsOfRaw": "08/03/2026",
  "window": {
    "startDate": "2026-07-01",
    "endDate": "2026-08-04"
  },
  "recipient": {
    "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C",
    "recipientLevel": "C",
    "name": "APPLE INC",
    "uei": "HJAKCN4NEU95",
    "attributionStatus": "verified_by_exact_recipient_id_and_uei",
    "detailUrl": "https://api.usaspending.gov/api/v2/recipient/09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C/"
  },
  "awards": [
    {
      "awardId": "19FR6326K0799",
      "awardType": "PURCHASE ORDER",
      "awardingAgency": "Department of State",
      "awardingSubAgency": null,
      "actionDate": "2026-07-30",
      "modification": "0",
      "transactionAmount": 15236.93,
      "recipientName": "APPLE INC",
      "recipientUei": "HJAKCN4NEU95",
      "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C",
      "internalId": "123",
      "generatedInternalId": "generated-1"
    }
  ],
  "resultCount": 1,
  "partial": false,
  "sourceStats": {
    "operations": 3,
    "attempts": 3,
    "decodedBytes": 12345
  },
  "deliveryIntent": {
    "event": "result-found",
    "businessRows": 1
  }
}

Every award has the verified recipient ID and UEI. queriedAt is observation time; sourceAsOf is the date reported by the source freshness endpoint.

Statuses and agent guidance

Agents should branch on the closed status value. Do not interpret an absent Dataset row as a successful empty search without reading OUTPUT.

Status	Meaning	Agent action
SUCCEEDED	One exact-attributed snapshot was delivered; resultCount is 1 to 25.	Consume the Dataset row. If partial is true, label it first-page partial and do not infer completeness.
NO_RESULTS	The exact recipient, freshness response, and transaction response were valid; page 1 had zero results and hasNext was false.	Treat as a valid empty snapshot. A later run with a new window is allowed; there is no result charge.
IDENTITY_UNVERIFIED	The child ID was not verified by the detail response, or the recognized exact ID-not-found response was returned.	Repair or re-resolve the recipient ID. Do not substitute a name, UEI, parent ID, or fuzzy match.
INVALID_INPUT	Closed input validation failed before network access.	Fix the payload and retry after validation. No source work or result charge occurred.
SOURCE_ERROR	A source transport, HTTP, timeout, redirect, or exhausted retry failure occurred.	Retry conservatively with the same input for a transient source failure; repeated failures need source/operator review.
SOURCE_CONTRACT_VIOLATION	The source response or a transaction changed shape, identity, bounds, or required evidence.	Do not treat it as empty. Stop automated retries until the source or Actor contract is reviewed.
BUDGET_STOP	The buyer budget could not cover the combined result event and Dataset cost before source access.	Raise the run budget and start a new snapshot.
PRICING_MISCONFIGURED	Required PPE pricing was missing, malformed, or the default Dataset event was positive.	Stop and notify the Actor operator; do not loop.
DELIVERY_UNKNOWN	Source work produced a candidate, but linked Dataset delivery/charging did not return confirmed success.	Do not automatically retry: a row may exist and billing may be unknown. Reconcile the run before any new snapshot.

DELIVERY_UNKNOWN is deliberately conservative. An exception, missing linked-call result, or chargedCount < 1 is not retried. If the linked call reports chargedCount >= 1, the row is treated as paid even if eventChargeLimitReached prevents additional work.

Pricing and discounts

Pay-per-event pricing uses one automatic apify-actor-start event per run and one custom result-found event for one successful snapshot. The default Dataset item event must be absent or priced at $0.00000. A no-result, identity failure, source failure, invalid input, budget stop, or pricing failure emits no result-found event.

Tier	Discount	Run start (apify-actor-start)	Snapshot result (result-found)	One successful snapshot total
FREE	0%	$0.00500	$0.01500	$0.02000
BRONZE	5%	$0.00475	$0.01425	$0.01900
SILVER	10%	$0.00450	$0.01350	$0.01800
GOLD	15%	$0.00425	$0.01275	$0.01700
PLATINUM	18%	$0.00410	$0.01230	$0.01640
DIAMOND	20%	$0.00400	$0.01200	$0.01600

The start event is charged once per run. The result event is charged once only when the single linked Dataset push reports delivery with chargedCount >= 1. Repeating the same input is a new point-in-time snapshot and a new billable run; this Actor has no replay or cross-run deduplication semantics.

API

Start a run with an Apify API token and the exact JSON input:

curl -sS -X POST 'https://api.apify.com/v2/acts/zinin~us-brand-federal-award-snapshot/runs?waitForFinish=60' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"recipientId":"09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C","startDate":"2026-07-01","endDate":"2026-08-04","maxResults":10,"requestId":"prefill-apple-contracts-2026-08"}'

For a completed run, read the Dataset using its defaultDatasetId:

curl -sS "https://api.apify.com/v2/datasets/$DEFAULT_DATASET_ID/items?clean=true&format=json" \
  -H "Authorization: Bearer $APIFY_TOKEN"

Read the run's OUTPUT KVS record through the Apify run/KVS API when you need the terminal status, including no-result and delivery-unknown outcomes.

JavaScript SDK

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = {
  recipientId: '09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C',
  startDate: '2026-07-01',
  endDate: '2026-08-04',
  maxResults: 10,
  requestId: 'prefill-apple-contracts-2026-08',
};

const run = await client.actor('zinin/us-brand-federal-award-snapshot').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

For agents, read OUTPUT as the authority for terminal status before assuming that a Dataset item was successfully delivered.

MCP

When an Apify MCP client exposes the standard call-actor tool, send:

{
  "name": "call-actor",
  "arguments": {
    "actor": "zinin/us-brand-federal-award-snapshot",
    "input": {
      "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C",
      "startDate": "2026-07-01",
      "endDate": "2026-08-04",
      "maxResults": 10,
      "requestId": "prefill-apple-contracts-2026-08"
    }
  }
}

Related Actors

These existing public zinin Actors complement a federal award snapshot with company identity, US filing, procurement, or counterparty checks:

Actor	What it does
Company Registry Enricher	Resolve official registry identity, status, jurisdiction, and optional UK registry enrichment.
Company Profile Lookup	Combine a company domain or name with a GLEIF registry match and public technology signals.
SEC EDGAR Filing Watcher	Retrieve recent SEC filing metadata for public-company tickers.
Gov Tender Radar	Search public-sector procurement notices from TED Europa by keyword or CPV code.
Counterparty Risk Rollup	Combine sanctions, registry, litigation, and hiring checks for a counterparty.

Public-data and storage notice

USAspending observations are public source data. This Actor does not certify that a recipient owns a brand, that an award is valid, that a company has a particular legal status, or that the returned page is a complete history. It is not legal, procurement, compliance, accounting, or investment advice. Review the cited source and apply your own decision rules.

The Actor stores the public recipient and award observations plus run metadata in the run's Apify Dataset and OUTPUT KVS record. It sends no result to external storage and keeps no cross-run state. Retention and deletion follow your Apify storage and account settings; manage retained run storage and delete the Dataset or KVS record in Apify when it is no longer needed. No API key, proxy credential, or buyer secret is accepted by this Actor.

x402 and agentic use

The fixed JSON input, closed status enum, bounded work, deterministic output, and single-snapshot billing unit make this Actor suitable for agentic calls and payment-aware x402 orchestration around an Apify run. An agent should authenticate with its normal Apify integration, pass the exact recipient ID, check OUTPUT, and stop on DELIVERY_UNKNOWN. This README does not claim external catalog registration or an x402 listing.

FAQ

Can I search by Apple, a legal name, UEI, or another business identifier? No. V1 deliberately accepts only the exact lowercase USAspending child recipient ID ending in -C. Resolve and validate that identifier before calling this Actor.

Does the Actor return all federal awards? No. It requests only the first page, accepts only prime contract award type codes A, B, C, and D, and returns at most 25 transactions. partial: true means the source reported more rows on that first-page query; it does not mean later pages were fetched.

What does NO_RESULTS mean? It means the exact recipient and source contracts were verified, the first page was valid and complete, and it contained zero transactions. It is different from IDENTITY_UNVERIFIED, SOURCE_ERROR, and SOURCE_CONTRACT_VIOLATION.

Will the Actor retry a failed request? Only the bounded source retry policy applies: one retry maximum per operation for the listed transient statuses and transport failures. Agents may retry a SOURCE_ERROR run conservatively, but should repair inputs for INVALID_INPUT and IDENTITY_UNVERIFIED, investigate contract drift for SOURCE_CONTRACT_VIOLATION, and never auto-retry DELIVERY_UNKNOWN.

Is this a monitoring or change-feed Actor? No. Each run is a new point-in-time snapshot. The Actor has no cross-run baseline, replay, deduplication, or change-feed state.

How is a successful snapshot billed? One run-start event is charged for the run. A valid snapshot is delivered through one linked result-found Dataset push and charged once only when delivery reports chargedCount >= 1. A delivery exception can leave the billing state unknown, so DELIVERY_UNKNOWN must be reconciled before another call.

Can an AI agent call it? Yes. Use the Apify API, JavaScript SDK, or a standard Apify MCP call-actor integration, then branch on the OUTPUT status rather than guessing from Dataset presence.

Built by zinin.