# US Brand Federal Award Snapshot (`zinin/us-brand-federal-award-snapshot`) Actor Return one bounded official USAspending snapshot of up to 25 prime contract transactions for one exact child recipient ID and date window. - **URL**: https://apify.com/zinin/us-brand-federal-award-snapshot.md - **Developed by:** [Tim Zinin](https://apify.com/zinin) (community) - **Categories:** MCP servers, News - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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: ```json { "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`](https://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](https://api.usaspending.gov/docs/endpoints), [recipient API contract](https://github.com/fedspendingtransparency/usaspending-api/blob/master/usaspending_api/api_contracts/contracts/v2/recipient.md), and [spending-by-transaction API contract](https://github.com/fedspendingtransparency/usaspending-api/blob/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_transaction.md). ### 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`. ```json { "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: ```json { "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: ```bash 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`: ```bash 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 ```js 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: ```json { "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](https://apify.com/zinin/company-registry-enricher) | Resolve official registry identity, status, jurisdiction, and optional UK registry enrichment. | | [Company Profile Lookup](https://apify.com/zinin/company-lookup) | Combine a company domain or name with a GLEIF registry match and public technology signals. | | [SEC EDGAR Filing Watcher](https://apify.com/zinin/sec-edgar-watcher) | Retrieve recent SEC filing metadata for public-company tickers. | | [Gov Tender Radar](https://apify.com/zinin/gov-tender-radar) | Search public-sector procurement notices from TED Europa by keyword or CPV code. | | [Counterparty Risk Rollup](https://apify.com/zinin/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](https://apify.com/zinin). # Actor input Schema ## `recipientId` (type: `string`): USAspending lowercase child recipient ID ending in -C. ## `startDate` (type: `string`): Inclusive YYYY-MM-DD start date; runtime validation enforces the calendar and 2007-10-01 lower bound. ## `endDate` (type: `string`): Inclusive YYYY-MM-DD end date, no later than the UTC run date. ## `maxResults` (type: `integer`): Maximum number of exact-attributed transactions in the one snapshot row. ## `requestId` (type: `string`): Optional bounded correlation label; it is not replay state. ## Actor input object example ```json { "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C", "startDate": "2026-07-01", "endDate": "2026-08-04", "maxResults": 10, "requestId": "prefill-apple-contracts-2026-08" } ``` # Actor output Schema ## `OUTPUT` (type: `string`): API link to the closed OUTPUT KVS envelope. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input 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" }; // Run the Actor and wait for it to finish const run = await client.actor("zinin/us-brand-federal-award-snapshot").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C", "startDate": "2026-07-01", "endDate": "2026-08-04", "maxResults": 10, "requestId": "prefill-apple-contracts-2026-08", } # Run the Actor and wait for it to finish run = client.actor("zinin/us-brand-federal-award-snapshot").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C", "startDate": "2026-07-01", "endDate": "2026-08-04", "maxResults": 10, "requestId": "prefill-apple-contracts-2026-08" }' | apify call zinin/us-brand-federal-award-snapshot --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=zinin/us-brand-federal-award-snapshot", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/GK5rOaw0TxofetGQh/builds/UHc03IMbN2gD6cWrR/openapi.json