{ "openapi": "3.0.1", "info": { "title": "USAspending Government Spending Data Scraper — Subawards", "description": "Every US federal procurement data: contract, IDV, grant, loan and direct payment from USAspending.gov's awards API — plus sub-contracts and sub-grants, joined to the prime award. 54 typed fields incl. recipient UEI/address, NAICS/PSC, CFDA. Filter by agency, keyword, state, date. Spending data API.", "version": "0.1", "x-build-id": "yQCtlL7qQ3r86XQfC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetchsmith~us-federal-awards-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetchsmith-us-federal-awards-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/fetchsmith~us-federal-awards-scraper/runs": { "post": { "operationId": "runs-sync-fetchsmith-us-federal-awards-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/fetchsmith~us-federal-awards-scraper/run-sync": { "post": { "operationId": "run-sync-fetchsmith-us-federal-awards-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrl": { "title": "Start from a usaspending.gov search link", "type": "string", "description": "Paste a usaspending.gov Advanced Search \"share\" link (usaspending.gov/search?hash=... or usaspending.gov/search/...) instead of picking \"Keywords\"/\"Award categories\" by hand — this Actor resolves the site's own saved-search hash and applies its keyword and award-type filters, overriding those two inputs. Other filters set in that search (agency, location, NAICS/PSC, award amount, custom date range) are NOT carried over yet — a warning names any of those it finds so you can set the matching input yourself. Leave empty for a normal search built from the inputs below." }, "awardLevel": { "title": "Award level (prime or sub-award)", "enum": [ "prime", "subaward" ], "type": "string", "description": "\"Prime\" returns the federal award itself (the default). \"Sub-award\" returns the FSRS sub-contract / sub-grant records filed *under* prime awards — who the prime contractor actually paid, with the prime award ID and URL on every row so you can join back. Every filter below applies in both modes, but in sub-award mode they target the sub-recipient (e.g. \"Recipients\" and \"Recipient states\" match the sub-awardee, and \"Award IDs\" matches the PRIME award ID and returns all of its sub-awards). Only prime awards whose recipient filed FSRS reports have sub-awards, so sub-award mode returns fewer rows.", "default": "prime" }, "awardCategories": { "title": "Award categories", "type": "array", "description": "Which kinds of federal awards to pull. Each category is fetched with its own query (the API refuses to mix contract and grant codes in one request), then merged into one dataset.", "items": { "type": "string", "enum": [ "contracts", "idvs", "grants", "direct_payments", "other_financial_assistance", "loans" ], "enumTitles": [ "Contracts (BPA calls, purchase/delivery orders, definitive contracts)", "IDVs (GWAC, IDC, FSS, BOA, BPA)", "Grants (block, formula, project, cooperative agreements)", "Direct payments", "Other financial assistance", "Loans (face value + subsidy cost instead of obligated amount)" ] }, "default": [ "contracts" ] }, "startDate": { "title": "Start date", "type": "string", "description": "Earliest date for USAspending's award-level time_period filter, YYYY-MM-DD. Defaults to one year ago. This is a coarse recency bound, not a strict window - no date on the returned row is guaranteed to fall inside it (see the README FAQ). The API has no data before 2007-10-01, so earlier dates are clamped." }, "endDate": { "title": "End date", "type": "string", "description": "Latest date for USAspending's award-level time_period filter, YYYY-MM-DD. Defaults to today. Moving this end date is what actually changes which awards match; narrowing the start barely does (see the README FAQ)." }, "keywords": { "title": "Keywords", "type": "array", "description": "Free-text search across award description, recipient and agency. Multiple keywords are ORed by the API.", "items": { "type": "string" } }, "agencies": { "title": "Awarding agencies", "type": "array", "description": "Top-tier awarding agency names, e.g. \"Department of Energy\", \"Department of Defense\", \"National Aeronautics and Space Administration\". Case-insensitive -- corrected automatically against USAspending's 111 top-tier agency names (logged when corrected). Abbreviations and unrecognised names still match nothing. Multiple values are ORed.", "items": { "type": "string" } }, "fundingAgencies": { "title": "Funding agencies", "type": "array", "description": "Top-tier funding agency names (the agency whose budget actually pays, which can differ from the awarding agency on pass-through grants). Same case-insensitive correction and exact-name rule as Awarding agencies, and multiple values are ORed the same way. Setting this alongside Awarding agencies does NOT OR across the two -- the award must match both at once (see the README FAQ).", "items": { "type": "string" } }, "recipients": { "title": "Recipients", "type": "array", "description": "Free-text recipient name search, e.g. \"Lockheed Martin\". Matches the same box as USAspending's Advanced Search → Recipient. Multiple values are ORed.", "items": { "type": "string" } }, "awardIds": { "title": "Award IDs (exact lookup)", "type": "array", "description": "Exact PIID / FAIN / URI values, e.g. \"N0001917C0001\". When set, this becomes an exclusive lookup: every other filter (keywords, agencies, recipients, states, amounts, date window) is ignored and the full 2007-10-01..today date range is used, so an exact-ID lookup can never be silently hidden by an unrelated filter.", "items": { "type": "string" } }, "placeOfPerformanceStates": { "title": "Place-of-performance states", "type": "array", "description": "Two-letter USPS state codes for where the work is performed, e.g. CA, TX.", "items": { "type": "string" } }, "recipientStates": { "title": "Recipient states", "type": "array", "description": "Two-letter USPS state codes for the recipient's own address, e.g. NY, VA.", "items": { "type": "string" } }, "recipientTypes": { "title": "Recipient business types", "type": "array", "description": "Filter to recipients matching one or more USAspending business-type categories, e.g. small_business, woman_owned_business, veteran_owned_business, minority_owned_business, nonprofit, higher_education, sole_proprietorship, manufacturer_of_goods (live-verified 2026-09-18; USAspending has more categories beyond these). Multiple values are ORed. A misspelled category returns zero rows rather than an error — double-check spelling against USAspending's own advanced search if a run comes back empty.", "items": { "type": "string" } }, "naicsCodes": { "title": "NAICS codes", "type": "array", "description": "Filter to one or more NAICS industry codes, e.g. 541511 (custom computer programming). 2-6 digit prefixes are all accepted — 5415 matches every 6-digit code under it. Multiple codes are ORed. Grants/direct payments/other financial assistance/loans have no NAICS, so this filter returns nothing for those categories.", "items": { "type": "string" } }, "pscCodes": { "title": "PSC codes", "type": "array", "description": "Filter to one or more Product or Service Codes (PSC), e.g. `R425` (engineering/technical services). 1-4 character prefixes are all accepted — `R4` matches every professional-services code under it, `10` every weapons product code, `R` the whole services letter. Multiple codes are ORed. Only contracts and IDVs carry a PSC, so this filter returns nothing for grants/loans/direct payments — and an unrecognised code returns zero rows rather than an error, so check your spelling if a run comes back empty.", "items": { "type": "string" } }, "defCodes": { "title": "COVID-19 relief funding only (DEFC)", "type": "array", "description": "Restrict to awards funded under one or more COVID-19 Disaster Emergency Fund Codes (DEFC) — a structural flag USAspending stamps on the award's own funding line, not a keyword match against the description. Leave empty to search every award regardless of funding source. Multiple values are ORed. Works across every award category (contracts, grants, loans, direct payments, IDVs, sub-awards) since it filters on the funding line, not the award type. An unrecognised code is rejected by USAspending with a 400 naming the valid list, verified live 2026-09-28 — this field can never silently no-op. In sub-award mode (\"awardLevel\":\"subaward\") the filter still narrows correctly (matches the underlying prime award's funding line), but the output row has no `disasterEmergencyFundCodes` field at all — USAspending's own sub-award endpoint returns a null code even when explicitly requested, verified live 2026-09-28. Use \"awardLevel\":\"prime\" if you need the matched code visible on the row.", "items": { "type": "string", "enum": [ "L", "M", "N", "O", "P", "U", "V" ], "enumTitles": [ "L — Coronavirus Preparedness and Response Act 2020", "M — Families First Coronavirus Response Act", "N — CARES Act", "O — CARES/PPP/Consolidated Approp. 2021/ARPA (shared non-emergency code)", "P — Paycheck Protection Program and Health Care Enhancement Act", "U — Consolidated Appropriations Act 2021", "V — American Rescue Plan Act of 2021" ] }, "default": [] }, "minAwardAmount": { "title": "Minimum award amount (USD)", "minimum": 0, "type": "integer", "description": "Only return awards at or above this obligated amount." }, "maxAwardAmount": { "title": "Maximum award amount (USD)", "minimum": 0, "type": "integer", "description": "Only return awards at or below this obligated amount." }, "expiringWithinDays": { "title": "Expiring within (days) — recompete finder", "minimum": 1, "type": "integer", "description": "Only return awards whose period of performance ends within this many days from today (0 to N, never already-expired). Turns this into a recompete radar: contracts and grants coming up for re-bid or renewal. Applied client-side after fetching — USAspending's own filters can only search by award action date, not period-of-performance end date, so a broad, mostly-expired date range plus a tight amount/agency filter narrows the scan before this cuts it further. Not supported in awardLevel=\"subaward\" mode (sub-award records carry no period-of-performance end date), nor for the \"idvs\" and \"loans\" categories — USAspending reports no period-of-performance end date for either, so rows in those categories are always dropped. All three cases warn in the log rather than silently returning zero rows, and unmatched rows are never charged. Leave empty for a normal award search." }, "expiringAfterDays": { "title": "Expiring after (days) — bid lead time", "minimum": 0, "type": "integer", "description": "Skip awards expiring sooner than this many days out. A contract ending next week is too late to prepare a bid for; a typical lead time is 90-180 days. Requires \"Expiring within\" above to also be set — ignored (with a warning) otherwise, and must be smaller than it." }, "includeOpportunityScore": { "title": "Include opportunity score (0-100)", "type": "boolean", "description": "Adds an `opportunityScore` field (0-100, higher = more worth pursuing) to every row, computed by a fixed, documented formula — never an AI/LLM call. Weights: award size (0-40, log-scaled so a $50M+ mega-award doesn't swamp everything), a tech/priority-sector keyword match in the description/NAICS/PSC text (0-25 — checked against your own \"Keywords\" input if set, else a fixed list: AI, cyber, cloud, solar, biotech, quantum, etc.), award category (0-15 — IDVs/BPAs score highest as an ongoing multi-year vehicle, then contracts, then grants/assistance/loans), and recompete urgency (0-20 — higher the sooner the period of performance ends, 0 past 365 days out or already expired). See the README for the exact formula. Prime mode only (awardLevel=\"prime\") — ignored with a warning in sub-award mode, which has no period-of-performance end date to score urgency from. Off by default so it never changes the default output shape.", "default": false }, "sortBy": { "title": "Sort by", "enum": [ "awardAmount", "lastModifiedDate", "startDate", "recipientName" ], "type": "string", "description": "Ordering of results within each category. Loans are sorted by loan value / issued date, which are their equivalents of amount / start date. In sub-award mode the equivalents are sub-award amount / sub-award date / sub-awardee name; sub-awards carry no last-modified date, so that option falls back to sub-award date.", "default": "awardAmount" }, "order": { "title": "Sort order", "enum": [ "desc", "asc" ], "type": "string", "description": "Whether the sort field runs high-to-low (descending, e.g. biggest awards first) or low-to-high.", "default": "desc" }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop after this many awards in total (across all selected categories). You are only charged for awards actually returned.", "default": 100 }, "maxPagesPerCategory": { "title": "Max pages per category", "minimum": 1, "maximum": 200, "type": "integer", "description": "Safety cap on how deep to paginate each category (100 awards per page).", "default": 50 }, "watchLabel": { "title": "Watch label (only-new-since-last-run alerts)", "type": "string", "description": "Set a name for this saved search to turn on watch mode. The first run for a given label + filter combination is a free baseline: it records every award (or sub-award, in sub-award mode) currently matching your filters and returns zero rows, charged nothing. Run the same label and filters again later — on a schedule, typically — and you get back only what is new since the last run; anything already delivered is skipped and not charged. Works in both prime and sub-award mode. Changing any filter (categories, keywords, agencies, recipients, states, NAICS/PSC codes, amount bounds, award IDs, or an explicitly-set start/end date) starts a fresh baseline under that label — leaving start/end date on their rolling defaults does not, since those move every day on their own." }, "watchChanges": { "title": "Also alert on award changes (prime mode only)", "type": "boolean", "description": "Only used with watchLabel, and only in prime mode (awardLevel not set to \"subaward\"). When on, an award you were already alerted on is re-delivered (charged again) if USAspending's own Last Modified Date moves, or its amount, outlays or end date changes (e.g. a contract modification, an option exercised, a period of performance extended) — tagged with _watchChangeType and _watchPrevious showing exactly what moved. Off by default, so a plain watchLabel only ever alerts on brand-new awards/sub-awards, same as before this option existed.", "default": false }, "webhookUrl": { "title": "Webhook URL (notify on completion)", "type": "string", "description": "Optional. An http(s) URL to POST a small JSON summary to when the run finishes — awards/sub-awards pushed, rows scanned, and watch-label new/changed counts if Watch label is set. A convenience for callers who want a completion ping without setting up an Apify platform webhook (which needs separate Console/API configuration per Task, not per run). Best-effort: a failed or slow webhook is logged as a warning and never fails the run or affects charging — it fires after every row has already been pushed and charged. Leave empty to skip." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }