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 - both contracts accept 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 the source snapshot; public 1.1 adds an evidence-to-action decision layer, while current-run OUTPUT reconciles work, delivery, settlement, KVS recovery, and replay safety.

Who uses it

• Procurement and supplier-intelligence teams checking a known USAspending child recipient.
• Account, research, and public-sector teams that need a bounded transaction snapshot with source identity.
• Data engineers joining a deterministic public award observation to an existing company record.
• Agents that can obey a closed status contract and always leave procurement or legal interpretation to a human.
• 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

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:

{
  "schemaVersion": "1.1",
  "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 contract

Field	Required	Limits and meaning
schemaVersion	no	Store default 1.1 adds decision and current-run receipt fields. Explicit 1.0 and omitted-version API inputs preserve frozen legacy Dataset and OUTPUT shapes.
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 both versions.
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.

Sources and rights

The only source is the official USAspending API at api.usaspending.gov. Both output contracts use 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 contract

Successful OUTPUT envelope

Every run attempts one compact OUTPUT KVS record. The Store default 1.1 binds the receipt to the current Apify run and reconstructs work, Dataset delivery, named-event settlement, bounded recovery, terminal outcome, and replay safety.

{
  "schemaVersion": "1.1",
  "actor": "us-brand-federal-award-snapshot",
  "runId": "your-current-run-id",
  "requestId": "prefill-apple-contracts-2026-08",
  "status": "SUCCEEDED",
  "errorCode": null,
  "message": "One exact-recipient snapshot row was delivered and charged.",
  "found": true,
  "resultCount": 1,
  "partial": false,
  "datasetId": "your-run-dataset-id",
  "inputDigest": "sha256-of-canonical-normalized-input",
  "sourceStats": {
    "operations": 3,
    "attempts": 3,
    "decodedBytes": 12345
  },
  "delivery": {
    "datasetWrite": "confirmed",
    "settlement": "paid",
    "defaultDatasetBillingEvent": "absent",
    "resultEvent": "result-found",
    "customEventCountBefore": 0,
    "customEventCountAfter": 1,
    "customEventCountDelta": 1,
    "aggregateChargedCount": 2,
    "eventChargeLimitReached": true,
    "chargeableWithinLimit": {
      "apify-actor-start": 0,
      "result-found": 0
    },
    "confirmedDatasetWrites": 1,
    "confirmedResultEvents": 1,
    "confirmedCharges": 1,
    "chargedCount": 1
  },
  "run": {
    "requestedCount": 1,
    "uniqueCount": 1,
    "duplicateCount": 0,
    "successfulCount": 1,
    "failedCount": 0,
    "unprocessedCount": 0,
    "deliveredRowCount": 1,
    "paidRowCount": 1,
    "freeRowCount": 0,
    "withheldRowCount": 0,
    "anomalousChargeCount": 0,
    "ambiguousDeliveryCount": 0,
    "ambiguousSettlementCount": 0,
    "partial": false,
    "budgetStopped": false,
    "fatalError": null,
    "replaySafe": false,
    "safeToAutomate": false
  },
  "terminal": {
    "primaryKvsWrite": "confirmed",
    "recoveryKvsWrite": "not_attempted",
    "exit": "requested"
  }
}

sourceStats is intentionally reduced to exactly operations, attempts, and decodedBytes. It has no row-count, identity-mismatch, invalid-row, or duplicate hasNext fields. The named result-found counter is the settlement source of truth: a successful run requires exact 0 → 1. The aggregate linked-push receipt is validated independently and cannot override named-event settlement.

Explicit schemaVersion: "1.0" and omitted-version API inputs keep the frozen ten-key legacy OUTPUT envelope. That compatibility branch has no runId, delivery matrix, run counters, terminal recovery fields, or replay flag; callers that need those facts should select 1.1.

Frozen 1.0 Dataset row

The paid product unit is one bounded snapshot. This sample is the frozen 1.0 shape preserved for explicit 1.0 and omitted-version API callers:

{
  "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.

Enhanced 1.1 decision layer

Schema 1.1 keeps every 1.0 source field and adds only inputDigest plus decision. The decision block is evidence-to-review guidance, not an automated procurement, legal, ownership, compliance, accounting, or investment decision.

{
  "inputDigest": "sha256-of-canonical-normalized-input",
  "decision": {
    "decisionSchemaVersion": "1.0",
    "recordType": "us_brand_federal_award_snapshot",
    "entityId": "usa-spending-recipient:09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C",
    "eventId": "federal-award-window:stable-24-hex-window-digest",
    "observedAt": "2026-08-04T00:00:00.000Z",
    "freshness": {
      "status": "fresh",
      "asOf": "2026-08-03",
      "basis": "usa_spending_awards_last_updated"
    },
    "change": {
      "status": "not_measured",
      "previousEventId": null,
      "basis": "stateless_point_in_time_snapshot"
    },
    "confidence": {
      "score": 90,
      "band": "high",
      "basis": "exact_recipient_id_and_uei_match_on_bounded_official_api_snapshot",
      "gaps": [
        "first_source_page_only",
        "award_validity_not_independently_verified",
        "recipient_ownership_not_inferred",
        "cross_run_change_not_measured"
      ]
    },
    "recommendedAction": "REVIEW_AWARD_SOURCE_EVIDENCE_AND_PARTIAL_BOUNDARY_BEFORE_USE",
    "priority": "review",
    "safeToAutomate": false,
    "failureDiagnostics": null,
    "billing": {
      "billingEligible": true,
      "billingIntent": "linked_push_result_found",
      "eventName": "result-found",
      "unit": "one_delivered_exact_recipient_federal_award_snapshot",
      "settlementSource": "current_run_kvs_output"
    }
  }
}

The stored row says only that it was eligible and intended for the linked result-found push. It does not claim paid, free, anomalous, or unknown settlement. Read the same run's OUTPUT.delivery and OUTPUT.run for those facts.

Stable IDs have narrow meanings:

• entityId is the validated USAspending child-recipient identifier, not a claim that the brand owns the recipient.
• eventId is deterministic for the exact recipient and inclusive date window. It identifies the requested observation window, not a source award or cross-run dedupe key.
• observedAt is the current source observation time.
• freshness.asOf is the date returned by the USAspending freshness endpoint.
• change.status is always not_measured because this Actor stores no cross-run baseline.
• confidence covers exact identity attribution and the bounded source contract. It does not score award validity, legal meaning, ownership, completeness beyond page one, or business impact.

Decision routing

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 result event after the automatic start spend was observed.	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.
RUN_IDENTITY_UNAVAILABLE	Enhanced mode could not bind the receipt to a valid hosted Apify run ID before source access.	Do not retry blindly; repair the hosted runtime identity path.
DELIVERY_ERROR	Enhanced mode detected pre-push identity/KVS failure, unknown Dataset delivery, unknown/free/anomalous settlement, or post-delivery KVS/exit failure.	Inspect errorCode, delivery, run, and terminal; never auto-retry a post-push state.
DELIVERY_UNKNOWN	Frozen 1.0 compatibility status for an unconfirmed linked delivery/settlement.	Do not automatically retry: a row may exist and billing may be unknown.

Enhanced delivery codes preserve the distinction that matters for reconciliation:

DELIVERY_ERROR.errorCode	Dataset fact	Settlement fact
dataset_identity_unavailable	no push attempted	not attempted
delivery_unknown	thrown push, Dataset outcome unknown	unknown
charge_counter_unavailable	push returned, one Dataset write confirmed	named settlement unknown
aggregate_receipt_invalid	push returned, one Dataset write confirmed	named counter still records free/paid/anomalous truth; aggregate proof invalid
result_uncharged	one Dataset write confirmed	exact named delta 0, free
result_charge_delta	one Dataset write confirmed	named delta greater than 1, anomalous
output/exit failure after delivery	preserves the existing Dataset fact	preserves the existing named settlement fact

A thrown push and a returned push are never conflated. Any post-push state has replaySafe: false; reconciliation is required before another run.

Happy, partial, and failure output

These are compact projections of real Apify runs. They are not invented customer stories, demand claims, accuracy claims, or estimates. The identifiers, source window, Dataset count, KVS status, event counters, and source result were read back from the named run. The first run proves the existing production product unit on a positive official-source result. The second proves the current candidate's bounded, current-run NO_RESULTS path and explains why that canary was not accepted as positive delivery evidence.

Positive production snapshot: Apple, July 2026

Production run XPfOt82niWo24W1vj used build UHc03IMbN2gD6cWrR. It completed SUCCEEDED, wrote exactly one frozen 1.0 Dataset row to Dataset iFjq4YwU1Ycr7g6hv, and stored its legacy terminal record in KVS w0IYjUqomNApmkrx3. The run ledger recorded exactly one apify-actor-start and one result-found. Its source request used the exact child recipient ID for APPLE INC, the inclusive window 2026-07-01 through 2026-08-04, and maxResults:10.

The row recorded one prime-contract transaction, 19FR6326K0799, with Action Date 2026-07-30, a transaction amount of 15236.93, recipient UEI HJAKCN4NEU95, and hasNext:false. Those facts are public source observations. They do not prove brand ownership, commercial importance, performance, legal meaning, or a complete award history.

{
  "evidenceAccepted": true,
  "runId": "XPfOt82niWo24W1vj",
  "buildId": "UHc03IMbN2gD6cWrR",
  "status": "SUCCEEDED",
  "datasetId": "iFjq4YwU1Ycr7g6hv",
  "keyValueStoreId": "w0IYjUqomNApmkrx3",
  "chargedEventCounts": {
    "apify-actor-start": 1,
    "result-found": 1
  },
  "input": {
    "recipientId": "09c94e6e-003f-7a9a-a6a9-2305eb5b6025-C",
    "startDate": "2026-07-01",
    "endDate": "2026-08-04",
    "maxResults": 10,
    "requestId": "prefill-apple-contracts-2026-08"
  },
  "dataset": {
    "rows": 1,
    "schemaVersion": "1.0",
    "recipientName": "APPLE INC",
    "recipientUei": "HJAKCN4NEU95",
    "resultCount": 1,
    "partial": false,
    "sourceAsOf": "2026-08-11",
    "operations": 3,
    "attempts": 3,
    "decodedBytes": 2036,
    "awardId": "19FR6326K0799",
    "actionDate": "2026-07-30",
    "transactionAmount": 15236.93
  },
  "output": {
    "schemaVersion": "1.0",
    "status": "SUCCEEDED",
    "found": true,
    "resultCount": 1,
    "partial": false,
    "datasetId": "iFjq4YwU1Ycr7g6hv"
  }
}

This run used the frozen compatibility path because its API input omitted schemaVersion. That is deliberate preserved behavior: omitted version means 1.0. It proves the paid snapshot unit and exact official-source identity, but it does not pretend that the old KVS envelope contains the enhanced 1.1 run/delivery lattice.

Current candidate no-result canary: same recipient, narrow 2020 window

Candidate run UPxhU1n8W4HEmDRUG used immutable build 1oaKOta6RXeEUoFsH with 256 MB, timeout 180 seconds, maxTotalChargeUsd:0.025, and no automatic restart. It completed SUCCEEDED, wrote zero Dataset rows, emitted no result-found, and stored the enhanced NO_RESULTS envelope in KVS 4SNBP5xP6evDpaRxZ. Its input window was only 2020-01-01 through 2020-01-02; the official first page was valid, complete, and empty. The Actor therefore behaved correctly, but the canary was insufficient as a positive paid-delivery proof. It was not retried.

{
  "evidenceAccepted": true,
  "runId": "UPxhU1n8W4HEmDRUG",
  "buildId": "1oaKOta6RXeEUoFsH",
  "status": "SUCCEEDED",
  "memoryMbytes": 256,
  "timeoutSecs": 180,
  "maxTotalChargeUsd": 0.025,
  "restartOnError": false,
  "datasetId": "2q0xz8UrRdejlrFlj",
  "keyValueStoreId": "4SNBP5xP6evDpaRxZ",
  "datasetRows": 0,
  "chargedEventCounts": {
    "apify-actor-start": 1,
    "result-found": 0
  },
  "output": {
    "schemaVersion": "1.1",
    "actor": "us-brand-federal-award-snapshot",
    "runId": "UPxhU1n8W4HEmDRUG",
    "requestId": "federal-award-example",
    "status": "NO_RESULTS",
    "errorCode": null,
    "message": "The exact source page was complete and empty.",
    "found": false,
    "resultCount": 0,
    "partial": false,
    "datasetId": null,
    "sourceStats": {
      "operations": 3,
      "attempts": 3,
      "decodedBytes": 1619
    },
    "run": {
      "requestedCount": 1,
      "uniqueCount": 1,
      "duplicateCount": 0,
      "successfulCount": 1,
      "failedCount": 0,
      "unprocessedCount": 0,
      "deliveredRowCount": 0,
      "paidRowCount": 0,
      "freeRowCount": 0,
      "withheldRowCount": 0,
      "anomalousChargeCount": 0,
      "ambiguousDeliveryCount": 0,
      "ambiguousSettlementCount": 0,
      "partial": false,
      "budgetStopped": false,
      "fatalError": null,
      "replaySafe": true,
      "safeToAutomate": false
    },
    "terminal": {
      "primaryKvsWrite": "confirmed",
      "recoveryKvsWrite": "not_attempted",
      "exit": "requested"
    }
  }
}

The Store and public Task now use the verified positive July–August 2026 window rather than that empty two-day historical window. A fresh read-only source preflight on 12 August 2026 again returned exact recipient name APPLE INC, UEI HJAKCN4NEU95, one transaction 19FR6326K0799, and hasNext:false. That GET/POST source check improves fixture selection; it is not represented as another Actor run or as settlement evidence.

Field dictionary

Field	Operational meaning	Downstream rule
schemaVersion	Closed Dataset contract selected by the caller.	Keep 1.0 and 1.1 parsers separate; never assume omitted fields are null.
requestId	Buyer correlation label, not idempotency state.	Store beside the Apify run ID; do not use it alone to suppress a later point-in-time run.
queriedAt	Actor observation time.	Keep as UTC ISO time and distinguish it from source freshness.
sourceAsOf	USAspending freshness date accepted by the source validator.	Preserve the raw and normalized source values.
window	Inclusive requested action-date interval.	Never reinterpret it as an award lifecycle or publication interval.
recipient	Exact source child-recipient identity and evidence URL.	Keep ID and UEI together; do not infer brand ownership.
awards	Bounded, sorted first-page prime-contract transactions.	Preserve the array before flattening; treat amounts as source observations, not revenue.
resultCount	Number of accepted transactions embedded in the one snapshot row.	Do not confuse it with Dataset row count or PPE units.
partial	Source reported an additional first page after the accepted bounded page.	Route to review and label exports as incomplete.
sourceStats	Bounded source operations, attempts, and decoded bytes.	Use for diagnostics, never as a coverage or accuracy score.
inputDigest	SHA-256 of canonical normalized 1.1 input.	Use for reconciliation; a digest is not encryption or anonymization.
decision	Evidence, gaps, manual action and settlement-neutral billing intent.	Preserve as JSON; never promote recommendedAction to an automatic procurement decision.
KVS OUTPUT	Current-run terminal and settlement receipt in 1.1.	Require matching runId, Dataset facts, named counter and terminal status before automation.

One Dataset row is one snapshot product unit even when awards contains many transactions. A free/no-result run may have no Dataset row and still have a complete KVS OUTPUT. Keep those two storage roles separate in warehouses and workflow tools.

Pricing

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 automatic start event is separate and applies to every run. Before source access, the Actor verifies the exact closed two-event price map, requires current spend to include the resolved tier's start price, requires result-found to begin at zero, and checks finite budgets in exact micro-USD. After the one linked push returns, the Actor requires the named counter to move exactly 0 → 1 and validates the closed aggregate receipt independently. Repeating the same input is a new point-in-time snapshot and a new start purchase; the successful 1.1 receipt therefore truthfully says replaySafe: false.

The Dataset decision contains billing eligibility and intent only. Current-run KVS OUTPUT is authoritative for whether the Dataset operation was confirmed and whether its named settlement was paid, free, anomalous, or unknown. The default Dataset-item event must remain absent or exactly zero-priced, so it is never added to the paid product unit.

Integration recipes

REST 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 '{"schemaVersion":"1.1","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 = {
  schemaVersion: '1.1',
  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": {
      "schemaVersion": "1.1",
      "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.

Evidence and boundaries

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.

Commercial playbooks

• Account research: attach the snapshot to a known company record, preserving the exact recipient ID, UEI, date window, source time, and public evidence URL without treating an award as buyer intent.
• Procurement review: route a positive or partial snapshot to an analyst who can inspect the current USAspending record and the surrounding award context before any supplier decision.
• Scheduled observations: retain independent point-in-time rows and calculate change downstream; this Actor does not claim a stored baseline or suppress a new paid snapshot across runs.
• Agentic orchestration: use the closed status enum and KVS reconciliation as a stop/go control for data handling, never as authority for procurement, legal, compliance, accounting, or investment action.

Operating guide

1. Resolve the exact lowercase child recipient ID ending in -C; never substitute a fuzzy company name.
2. Choose an inclusive date window that answers the current research question and stays within the bounds.
3. Keep schemaVersion explicit in integrations; omitted version intentionally selects frozen 1.0.
4. Preserve runId, Dataset ID, KVS ID, input, source time, and event counters together for reconciliation.
5. Stop automated processing on partial evidence, any delivery error, or any mismatch between Dataset, current-run OUTPUT, and the platform event ledger.
6. Apply buyer-controlled access, retention, deletion, and human review to the public award observations.

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 any enhanced DELIVERY_ERROR or frozen DELIVERY_UNKNOWN until reconciliation. 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. Both contract versions deliberately accept 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 enhanced DELIVERY_ERROR after a push or frozen 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. Enhanced success requires the named event counter to move exactly 0 → 1 and a valid closed aggregate receipt. A thrown push can leave Dataset delivery and billing unknown; a returned push can confirm Dataset delivery while named settlement remains unknown, free, paid, or anomalous. Read current-run OUTPUT 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.